Tous les articles

Back-end19 min de lecture

Qu'est-ce que le RAG ? Indexation, recherche et cas réel

Qu'est-ce que le RAG (Retrieval-Augmented Generation) ? Expliqué avec un cas réel : crawler, chunking, embeddings, vector store, recherche hybride, re-rank et sources.

Aussi en Português, English, Español

Si vous êtes arrivé ici en cherchant « qu'est-ce que le RAG », vous avez sûrement déjà vu le sigle dans des offres d'emploi, dans des articles sur l'IA et dans chaque produit qui promet de « discuter avec vos documents ». L'idée est bien plus simple que son nom.

J'ai construit un RAG de zéro : Nixa AI, un assistant de chat qui répond aux questions sur la documentation publique de NICE CXone, une plateforme de centre de contact. Vous posez la question en portugais, il cherche les bons passages dans la documentation officielle et répond en indiquant d'où il les a tirés. Le code est ouvert et se trouve sur GitHub.

Nixa : on pose la question en portugais, on reçoit la réponse avec le lien de la source

Cet article explique ce qu'est le RAG, comment fonctionne l'indexation (crawler, chunks, embeddings, vector store) et le parcours d'une question (recherche hybride, re-rank, prompt et sources), avec les vrais chiffres du projet.

TL;DR#

  • Le RAG, c'est chercher avant de répondre. L'application cherche des passages pertinents dans vos documents et les donne au modèle avec la question.
  • Il a deux moitiés : l'indexation, qui tourne avant (télécharger, découper, vectoriser, stocker), et la question, qui tourne à chaque message (chercher, classer, construire le prompt, générer).
  • Un embedding est un vecteur de nombres qui représente le sens d'un texte. Des textes proches deviennent des vecteurs proches.
  • La recherche par le sens seul rate les noms d'API. Dans Nixa, le score est à 75 % le sens et à 25 % les mots, puis un re-rank l'ajuste selon la source, le type de page et l'ancienneté.
  • Un index, un modèle d'embedding. Vous changez de modèle, vous réindexez tout.
  • Le RAG n'apprend rien au modèle, il lui donne seulement du contexte. Si la réponse n'est pas dans les documents, la bonne réaction est de dire qu'il ne l'a pas trouvée.

Le problème : le modèle n'a pas lu votre documentation#

Un LLM connaît ce qui figurait dans ses données d'entraînement jusqu'à une date limite. La documentation de votre produit, la release note de la semaine dernière, le wiki de l'équipe : il n'a rien vu de tout ça. Si vous lui posez la question quand même, il fait ce qu'il sait faire de mieux, c'est-à-dire écrire un texte plausible. Parfois juste, parfois avec un endpoint qui n'a jamais existé.

La documentation de CXone est vaste, répartie sur plusieurs sites (centre d'aide, portail développeurs, SDK sur GitHub) et presque entièrement en anglais. Trouver une réponse veut souvent dire ouvrir dix onglets. C'était le scénario parfait pour le RAG.

Qu'est-ce que le RAG#

RAG est le sigle de Retrieval-Augmented Generation : la génération augmentée par la recherche. Le nom vient d'un article de 2020 de chercheurs de Facebook AI, et l'idée tient en une phrase : avant de générer la réponse, récupérez les passages pertinents et mettez-les dans le prompt.

C'est un examen à livre ouvert. Le modèle reste celui qui écrit, mais au lieu de répondre de mémoire, il répond avec la page ouverte devant lui.

Il y a trois étapes :

  1. Retrieval (recherche) : trouver, dans une base de documents, les passages liés à la question.
  2. Augmentation : construire le prompt avec ces passages et la question.
  3. Generation (génération) : le LLM écrit la réponse à partir de ce contexte.

Les étapes 2 et 3 sont presque triviales. Presque tout le travail (et presque tous les bugs) se trouve dans la 1. Et pour bien chercher, la base doit avoir été préparée avant : c'est l'indexation.

RAG, fine-tuning ou tout coller dans le prompt ?#

Avant de construire, il vaut la peine de comprendre pourquoi pas les deux autres options évidentes.

Tout coller dans le promptFine-tuningRAG
PrincipeEnvoie les documents entiers à chaque questionRéentraîne le modèle avec vos donnéesCherche les passages pertinents et envoie seulement ceux-là
Nouveau documentIl suffit de le collerRéentraînerIndexer la nouvelle page
Coût par questionÉlevé : tous les tokens, à chaque foisFaibleFaible : quelques passages
Montre la sourceDifficileNonOui, chaque passage sait d'où il vient
Idéal pourQuelques documents courtsApprendre un style, un format, une tâcheUne grande base qui change et a besoin de sources

Tout coller fonctionne quand le contenu tient largement dans la fenêtre de contexte. Ce n'était pas mon cas : une seule des pages de release notes que j'ai indexées dépasse 140 000 caractères. Le fine-tuning apprend un comportement, n'est pas bon pour retenir des faits qui changent chaque semaine et ne dit pas d'où vient la réponse. Le RAG résout justement les deux choses dont j'avais besoin : un contenu qui change et une source dans chaque réponse.

Les deux moitiés d'un RAG#

Tout RAG a deux moitiés, qui tournent à des moments différents :

  • Indexation, avant toute question : récupérer les documents, les découper en morceaux, transformer chaque morceau en vecteur et le stocker.
  • Question, à chaque message : transformer la question en vecteur, trouver les morceaux les plus proches, les classer, construire le prompt et appeler le LLM.

Dans Nixa, l'indexation est une route de l'API que je lance depuis l'interface et qui renvoie sa progression en streaming. La question, c'est la route du chat.

L'indexation, étape par étape#

L'indexation de Nixa, avec les chiffres de l'index présent dans le dépôt

1. Le crawler : télécharger et nettoyer#

Le crawler part d'une liste de 154 URL de départ et ne suit que les liens de 11 domaines autorisés : le centre d'aide, le portail développeurs et les SDK officiels sur GitHub et npm. Les pages de connexion, les pages d'erreur, les fichiers binaires et les dépôts GitHub tiers restent dehors.

Pour chaque page, il télécharge le HTML et utilise Cheerio pour jeter tout ce qui n'est pas du contenu : menu, pied de page, bannière de cookies, « cette page vous a-t-elle été utile ? ». Ces déchets semblent inoffensifs, mais s'ils entrent dans l'index, ils apparaissent dans chaque résultat de recherche, puisqu'ils sont sur chaque page.

crawler.ts
import * as cheerio from "cheerio";
 
export async function crawlPage(url: string) {
  const html = await fetch(url).then((res) => res.text());
  const $ = cheerio.load(html);
 
  // The same menu on every page means noise in every search result
  $("nav, footer, header, script, style, .cookie-banner").remove();
 
  const title = $("h1").first().text().trim();
  const content = $("main, article").first().text().trim();
  if (content.length < 150) return null; // empty or error page
 
  const pageType = classify(url, title); // api, reference, guide, release
  return { url, title, content, breadcrumb: getBreadcrumb($), pageType };
}

En plus du texte, le crawler garde des métadonnées : titre, fil d'Ariane (un chemin du type « Agent > Copilot > Configurer »), le type de page (API, référence, guide, release note) et un hash SHA-256 du contenu. Le hash sert à économiser : à la prochaine indexation, si la page n'a pas changé, elle ne repasse pas par l'embedding. Et une page indexée il y a plus de deux semaines est téléchargée à nouveau.

Gardez les métadonnées en tête, elles reviennent dans le re-rank.

2. Le chunking : découper en morceaux#

On n'indexe pas la page entière. Une page d'API peut parler d'authentification, de pagination et de limites d'usage en même temps, et le vecteur de la page entière devient une moyenne de tout ça : il n'est proche d'aucune question précise. La page est donc découpée en chunks (morceaux).

Dans Nixa, la cible est de 900 caractères par chunk, et chaque chunk commence en répétant les dernières phrases du précédent, jusqu'à environ 200 caractères. C'est l'overlap (le chevauchement).

L'overlap : la fin d'un chunk ouvre le suivant. Et le titre voyage avec son paragraphe

L'overlap existe parce que la réponse ne respecte pas la frontière de votre découpe. Si la phrase qui explique le paramètre est restée à la fin d'un chunk et l'exemple au début du suivant, la répétition garantit qu'au moins l'un des deux contient les deux.

Autre détail : un paragraphe court qui ressemble à un titre (« Configurer le profil ») ne devient pas un chunk à lui seul. Il est collé au paragraphe suivant, pour que le passage emporte son sujet avec lui.

chunker.ts
export function chunkText(text: string, maxSize = 900, overlap = 200): string[] {
  const chunks: string[] = [];
  let current = "";
  let pendingHeading = "";
 
  for (const paragraph of text.split(/\n\n+/).map((p) => p.trim()).filter(Boolean)) {
    if (looksLikeHeading(paragraph)) {
      pendingHeading = paragraph; // glue it to the next paragraph
      continue;
    }
    const section = pendingHeading ? `${pendingHeading}\n${paragraph}` : paragraph;
    pendingHeading = "";
 
    if (current && current.length + section.length > maxSize) {
      chunks.push(current);
      // the next chunk starts with the last sentences of this one
      current = `${lastSentences(current, overlap)}\n\n${section}`;
    } else {
      current = current ? `${current}\n\n${section}` : section;
    }
  }
  if (current.length > 80) chunks.push(current);
  return chunks;
}

Remarquez que la découpe se fait par paragraphe (\n\n). Ça a une conséquence que je raconte à la fin de l'article.

3. Les embeddings : transformer le texte en vecteur#

Un embedding est une liste de nombres qui représente le sens d'un texte. Vous envoyez un texte à un modèle d'embedding et recevez un vecteur, du type [0.012, -0.341, 0.088, ...]. L'astuce, c'est que des textes de sens proche deviennent des vecteurs qui pointent dans des directions proches, même sans aucun mot en commun : « comment me connecter à l'API » se retrouve près de « authentication with OAuth ».

La taille du vecteur dépend du modèle. L'index de Nixa contient des vecteurs de 384 nombres (all-minilm, qui tourne en local avec Ollama) et de 3 072 nombres (la taille que renvoie gemini-embedding-001). L'application accepte trois fournisseurs d'embedding : Gemini (par défaut), OpenAI (text-embedding-3-small) et Ollama.

Une astuce peu coûteuse qui a aidé : avant de générer le vecteur, le titre de la page est placé devant le chunk. Un passage qui dit seulement « définissez la valeur sur true » ne veut rien dire tout seul. Avec [Configurer Copilot] devant, si. Anthropic décrit une version plus élaborée de cette idée, le contextual retrieval.

const input = `[${chunk.title}] ${chunk.content}`.slice(0, 2000);
const { embedding } = await embed(input); // number[]

4. Le vector store : stocker les vecteurs#

Le vector store est l'endroit où vivent les chunks, les vecteurs et les métadonnées. Et voici la partie qui surprend ceux qui s'attendent à une base vectorielle sophistiquée : dans Nixa, c'est un fichier JSON. Le data/vectorstore.json du dépôt contient 425 chunks issus de 62 pages et pèse 11 Mo.

Pour chercher, l'application lit le fichier, calcule la similarité entre la question et tous les chunks, puis trie. Force brute. Avec 425 chunks, c'est instantané. Avec des centaines de milliers, là oui, il vous faut un vrai index, comme pgvector sur Postgres ou une base vectorielle dédiée. Commencez simple et changez quand vous mesurez que c'est nécessaire.

La mesure de proximité la plus utilisée est la similarité cosinus : à quel point deux vecteurs pointent dans la même direction, sur une échelle de -1 à 1.

function cosineSimilarity(a: number[], b: number[]): number {
  if (a.length !== b.length) return 0; // vectors from different models
  let dot = 0, normA = 0, normB = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

Retenez cette première ligne. C'est la raison d'une des règles du projet.

La question, étape par étape#

Le parcours d'une question. La partie du haut n'utilise aucun LLM

1. L'expansion de la question : du portugais vers l'anglais#

La documentation est presque toute en anglais et les gens posent leurs questions en portugais. L'embedding s'en sort plutôt bien, mais la recherche par mots non : « relatório » (rapport) ne correspondra jamais à « reporting ».

La question devient donc deux : la sémantique est la question d'origine, et la lexicale reçoit des termes en anglais ajoutés à la fin. Il y a 19 règles, une par sujet :

const PT_EN_TERMS = [
  { pattern: /(relat[óo]rio|dashboard|m[ée]tricas)/i, en: "reporting analytics reports dashboard metrics KPI" },
  { pattern: /(fila|filas|roteamento|skill)/i, en: "queue queues skill skillset ACD routing" },
  { pattern: /(autentica[çc][ãa]o|login|oauth)/i, en: "authentication oauth bearer access login" },
  // ...
];
 
function buildQuery(question: string) {
  const extra = PT_EN_TERMS.filter((term) => term.pattern.test(question)).map((term) => term.en);
  return { semantic: question, lexical: [question, ...extra].join(" ") };
}

« Como gerar um relatório de filas? » (« comment générer un rapport de files d'attente ? ») part vers l'embedding telle que vous l'avez écrite, et vers la recherche lexicale avec « reporting », « queue », « ACD » et compagnie.

2. La recherche hybride : le sens et les mots#

La recherche purement sémantique est excellente pour les questions vagues et mauvaise pour les noms exacts. Si quelqu'un demande l'agent-sdk, vous voulez le passage qui contient ce mot, pas un qui parle de quelque chose de proche. La recherche par mots seule a le problème inverse : elle ne sait pas que « se connecter » et « login » sont la même chose.

La recherche hybride additionne les deux. Dans Nixa, le score de chaque chunk ressemble à ceci :

const isShort = question.split(/\s+/).length <= 2;
const semanticWeight = isShort ? 0.5 : 0.75;
const lexicalWeight = isShort ? 0.5 : 0.25;
 
// lexicalOverlap: share of the query words found in the chunk (0 to 1)
const score =
  cosineSimilarity(queryEmbedding, chunk.embedding) * semanticWeight +
  lexicalOverlap(lexicalQuery, chunk.content) * lexicalWeight;

Question normale : 75 % le sens, 25 % les mots. Une question de deux mots au plus passe à moitié-moitié, parce qu'avec si peu de texte l'embedding a peu de sens à capter, et le mot exact compte davantage.

La partie lexicale est la plus simple possible : la part des mots de la question qui apparaissent dans le chunk. On pourrait la remplacer par BM25 et faire mieux, mais ça a suffi pour trouver les bons noms d'API et de SDK.

De ce calcul sortent les 20 meilleurs candidats (quatre fois le nombre de passages qui vont dans le prompt, avec un minimum de 16), qui passent au re-rank.

3. Le re-rank : ce que la similarité ignore#

La similarité ne regarde que le texte. Mais je sais des choses que le texte ne dit pas : que la documentation officielle d'API vaut plus qu'un README quelconque, qu'une question technique veut une page de référence, que la release note d'hier vaut plus que celle de l'an dernier. C'est là qu'intervient le re-rank, en ajoutant des bonus et des pénalités au score :

SignalAjustement
Portail officiel des développeurs+0,15
Centre d'aide officiel+0,12
GitHub qui n'est pas celui des SDK officiels-0,40
Question technique et page d'API+0,12
Question technique et page de référence+0,10
Indexée il y a 7, 30 ou 90 jours au plus+0,06, +0,04 ou +0,02
Chaque mot de la question dans le titre+0,025
Un mot de la question dans le fil d'Ariane+0,08
La question entière dans le titre+0,15

Une question « technique », ici, c'est une question avec des mots comme api, sdk, webhook ou endpoint. Après l'ajustement, les chunks en double sont retirés, tout ce qui est sous 0,22 est écarté et les 5 meilleurs vont dans le prompt.

Valeurs d'exemple, avec les vrais poids de Nixa. Le même texte, selon la source, n'a pas le même destin

Le re-rank par règles est le plus simple qui existe. L'étape suivante serait un modèle de re-rank (un cross-encoder), qui lit la question et le passage ensemble et leur donne un score. Pour une base de cette taille, les règles ont suffi, et chacune est facile à expliquer quand un résultat paraît étrange.

4. Savoir quand ne pas répondre#

Avant d'appeler le LLM, Nixa regarde le score du meilleur passage et évalue la confiance : haute au-dessus de 0,6 avec au moins deux passages, moyenne au-dessus de 0,4, basse sinon. Avec une confiance basse ou aucun passage, il n'appelle même pas le modèle : il répond qu'il n'a pas trouvé cela dans la documentation officielle.

Ça paraît peu, mais c'est la différence entre un assistant utile et un générateur de suppositions avec de jolies sources. Si le contexte est faible, le modèle comble le vide avec ce qui semble plausible.

5. Le prompt#

Les 5 passages entrent dans le prompt système en XML, regroupés par type de page, chacun avec titre, URL et fil d'Ariane, et coupés à 700 caractères :

<context>
<section type="API">
<document index="1" type="api" url="https://docs.example.com/api/auth">
  <title>Authentication</title>
  <breadcrumb>Documentation > Getting Started</breadcrumb>
  <content>...</content>
</document>
</section>
</context>

Et les règles disent quoi en faire : répondre dans la langue de la question, citer la source dans le texte avec [Titre](URL) et, si l'information n'est pas dans le contexte, dire qu'elle n'a pas été trouvée dans la documentation officielle plutôt que d'inventer un endpoint, un champ ou une version. Quand deux sources se contredisent, l'ordre est : API, puis référence, puis guide, puis release note.

Le LLM peut être Gemini, OpenAI ou Ollama (100 % local). En changer ne modifie rien au RAG : le prompt reste le même.

6. Seulement les sources utilisées#

Beaucoup de RAG affichent sous la réponse tout ce que la recherche a renvoyé. Sauf que le modèle a peut-être utilisé deux des cinq passages, et alors trois « sources » sont décoratives.

Dans Nixa, la réponse arrive en streaming et, quand elle se termine, le serveur vérifie quelles URL apparaissent réellement dans le texte et n'envoie que celles-là :

export function selectCitedSources(answer: string, candidates: Source[]): Source[] {
  return candidates.filter((source) => answer.includes(source.url));
}

Une ligne. Comme le prompt demande de citer avec le lien, la source affichée en dessous est celle que le modèle a vraiment utilisée.

Un index, un modèle d'embedding#

Revenons à la première ligne du cosinus. Les vecteurs de modèles différents ne se comparent pas : ce sont des espaces différents, parfois même pas de la même taille. Entre un vecteur de 384 nombres d'all-minilm et un de 3 072 de Gemini, aucun calcul n'est possible, c'est pourquoi la fonction renvoie 0. Même quand la taille correspond, deux modèles organisent le sens différemment : on obtiendrait un score, mais il ne vaudrait rien.

C'est pour ça que la règle de Nixa est un embedding fixe par index. Le fichier enregistre quel fournisseur, quel modèle et quelle dimension ont produit les vecteurs, et la recherche utilise toujours ce même modèle pour vectoriser la question, quel que soit le LLM choisi pour le chat. On peut discuter avec Ollama et chercher avec Gemini. Si la dimension de la question ne correspond pas à celle de l'index, la recherche ne fait pas semblant : elle se replie sur la recherche lexicale seule et prévient dans le log qu'il faut réindexer.

const { embedding: queryEmbedding } = await getEmbedding(question, store.embeddingProvider);
 
if (store.dims && queryEmbedding.length !== store.dims) {
  console.warn("Embedding dimension mismatch, reindex. Falling back to lexical search.");
  return lexicalSearch(lexicalQuery);
}

Je l'ai appris à mes dépens. L'index présent aujourd'hui dans le dépôt mélange les deux : 330 chunks avec des vecteurs de 384 nombres, issus d'une indexation avec Ollama en local, et 95 avec 3 072, de Gemini. Pour une question vectorisée par Gemini, ces 330 ont une similarité nulle et n'apparaissent que par la partie lexicale, qui pèse 25 % du score. Plus des trois quarts de la base presque invisibles pour la recherche sémantique, et aucune erreur à l'écran.

Changer de modèle d'embedding, c'est changer l'index entier. Il n'existe pas de migration partielle.

La même recherche, hors du chat#

Comme la recherche ne dépend d'aucun LLM, elle est devenue une fonction à part, searchNiceDocs(), qui ne renvoie que des passages. Le chat l'appelle puis génère la réponse. Mais d'autres clients peuvent aussi l'appeler : elle est exposée comme tool MCP, search_nice_docs, et comme route REST.

Ainsi ChatGPT, Claude ou Cursor interrogent la même base, et c'est le modèle du client qui écrit la réponse. Si MCP est nouveau pour vous, j'en parle dans Qu'est-ce que MCP.

Quand le RAG ne suffit pas#

Le RAG est bon pour une chose : trouver le bon passage et répondre à partir de lui. Au-delà :

  • Les questions qui ont besoin de toute la base. « Combien d'API existe-t-il ? » ou « résume toutes les nouveautés de l'année » ne tiennent pas en 5 passages. Il faut une autre approche, comme une requête structurée ou un résumé préparé à l'avance.
  • Les données qui changent chaque minute. L'index est une photo. Dans Nixa, la question « quelle est la dernière version de l'agent SDK ? » ne passe même pas par le RAG : l'application interroge le registre npm sur le moment et répond avec la version et sa date de publication.
  • Les mauvais documents. Si la réponse n'est écrite nulle part, ou si elle est fausse, le RAG récupère fidèlement la mauvaise chose.
  • Changer le comportement du modèle. Le ton, le format, un type de tâche : ça relève du prompt ou du fine-tuning, pas de la recherche.
  • Une découpe ratée. Si le chunking sépare la question de la réponse, aucun re-rank ne vous sauvera. Ce qui m'amène au sujet suivant.

Ce que j'ai appris#

Découper par structure a un prix. Le chunker découpe par paragraphes (\n\n). Quand une page arrive sans aucune ligne vide, elle devient un seul paragraphe, et un seul chunk. Dans l'index actuel, 62 chunks dépassent 2 000 caractères, et le plus gros, une page de release notes, fait 142 273 caractères. L'embedding ne lit que les 2 000 premiers. Le reste existe dans le fichier et n'existe pas pour la recherche sémantique. La solution est une coupe de sécurité : si un paragraphe dépasse la limite, on le découpe par phrase.

Les métadonnées, c'est la moitié du classement. Le titre devant le chunk, le type de page, le fil d'Ariane et le domaine ont pesé plus sur les réponses que je ne l'imaginais. Et ils ne coûtent presque rien à garder dans le crawler.

Dire « je ne sais pas » est une fonctionnalité, pas un échec. Le score minimum et la confiance vérifiée avant d'appeler le LLM éliminent la réponse inventée qui trompe le plus : celle qui arrive avec ses sources.

Rendez la recherche observable. Avec RAG_DEBUG=true, chaque question journalise la requête étendue, le score de chaque passage et la confiance. Quand une réponse est fausse, le premier endroit où regarder, c'est la recherche, pas le LLM : si le bon passage n'est jamais arrivé dans le prompt, aucun modèle ne trouvera.

Commencez par un JSON. Un vector store dans un fichier, un cosinus écrit à la main, dix lignes de recherche lexicale. On comprend chaque nombre qui sort. La base vectorielle est une optimisation pour le jour où la base grandit.

Références#

  • Back-end
  • rag
  • ia
  • embeddings
  • llm
  • nextjs
  • typescript

Écrit par

Ingénieure logiciel et designer. J'écris sur ce que je rencontre en créant des apps, des APIs et des produits.