Assistant de documentation RAG avec MkDocs

La documentation a le plus de valeur quand on peut l’interroger sans perdre sa source de verite.

Le MkDocs RAG Documentation Assistant etait une exploration petite mais complete de cette idee : garder la documentation publiee comme systeme de reference, construire un index recuperable a partir d’elle, puis exposer une interface de chat qui repond avec des citations plutot qu’avec la memoire du modele seule.

La contrainte de design la plus importante etait la confiance. Un assistant de documentation ne devrait pas se comporter comme un chatbot generique avec un prompt sur les docs. Il devrait rendre le chemin de retrieval visible, conserver les metadonnees source et donner au lecteur un chemin de retour vers le materiel original.

Ce que fait le projet

Le projet combine un site de documentation MkDocs avec un pipeline Retrieval-Augmented Generation. Un utilisateur pose une question dans l’experience de documentation. Le backend valide la requete, embedde la question, recupere les chunks pertinents depuis un index vectoriel derive, construit un prompt ancre, demande a Gemini de generer une reponse, puis retourne la reponse et les citations.

Le workflow a quatre frontieres importantes :

• La frontiere documentation possede le markdown source et l’experience MkDocs pour le lecteur.
• La frontiere service RAG possede validation, embeddings, retrieval, prompt construction, generation et contrats API.
• La frontiere index derive possede la representation vectorielle, mais pas la verite. Elle peut etre reconstruite depuis les documents source.
• La frontiere operationnelle garde l’assistant aligne avec les changements de documentation grace a une reindexation controlee.

Workflow d’architecture de l’assistant de documentation RAG MkDocs.

Cette structure compte parce que l’assistant n’est utile que si chaque couche a une responsabilite claire :

• La documentation reste le system of record.
• Le vector store est une infrastructure derivee que l’on peut reconstruire.
• Le retriever reduit la fenetre de contexte aux sections pertinentes.
• La generation est contrainte par le contexte recupere.
• Les citations font partie du modele de confiance, pas seulement de la presentation.
• La reindexation est un workflow operationnel, pas un nettoyage manuel occasionnel.

Pourquoi MkDocs etait un bon frontend

MkDocs etait un bon choix parce qu’il gardait l’assistant proche du contenu source. Le contenu existait deja comme markdown structure, le modele de navigation etait familier, et l’assistant pouvait etre ajoute sans transformer le site de documentation en produit separe.

Le frontend utilisait :

• MkDocs avec le theme Material for MkDocs.
• Une interface de chat JavaScript legere.
• Un comportement responsive desktop et mobile.
• Le support light et dark mode.
• Des citations cliquables vers les sections pertinentes.

Le choix de design etait d’eviter que l’assistant ressemble a une application separee. Il devait rester a cote de la documentation, respecter la meme architecture d’information et aider le lecteur a passer rapidement de la question a la source citee.

Architecture backend

Le backend etait volontairement separe de l’UI de documentation. Cela gardait les secrets, appels modele, logique d’indexation et contrats API hors du navigateur, et rendait l’assistant deployable comme service plutot que comme script dans un site statique.

J’ai utilise FastAPI parce qu’il donne une surface API propre, une iteration rapide et un bon support des modeles de requete et de reponse types.

Les responsabilites du backend etaient :

• Accepter les requetes de chat depuis l’UI de documentation.
• Embedder les questions entrantes.
• Chercher les chunks pertinents dans le vector store.
• Formater le contexte recupere avec les metadonnees source.
• Appeler le modele de generation.
• Retourner la reponse finale et les citations.
• Exposer des endpoints de health et de reindexation.

Les principaux endpoints etaient :

• POST /api/chat : poser une question sur la documentation.
• GET /api/models : lister les options de modele disponibles.
• POST /api/reindex : reconstruire l’index vectoriel quand la documentation change.
• GET /health : health check du service.
• GET /docs : documentation API generee par FastAPI.

Cette frontiere rend le systeme plus simple a deployer, securiser, observer et modifier.

Ingestion des documents

Le pipeline d’ingestion est l’endroit ou beaucoup de systemes RAG deviennent fiables ou echouent silencieusement. Le modele ne peut citer que ce que la pipeline preserve. Le chunking et les metadonnees font donc partie du contrat produit, pas seulement du detail d’implementation.

Le processus commence avec les fichiers markdown du site de documentation :

1. Scanner le repertoire de docs configure.
2. Decouper les documents par titres.
3. Ajouter de l’overlap pour garder assez de contexte.
4. Generer des embeddings pour chaque chunk.
5. Stocker les vecteurs avec les metadonnees source.

Sans ces metadonnees, l’assistant peut encore repondre, mais il ne peut pas expliquer d’ou vient la reponse. Pour un assistant de documentation, la citation n’est pas une decoration. Elle fait partie du modele de confiance.

Retrieval et generation

Quand un utilisateur pose une question, le systeme embedde la requete avec le meme modele que celui utilise pendant l’indexation. Il effectue ensuite une recherche semantique dans le vector store et recupere les top-k chunks.

Le contexte recupere est formate dans un prompt puis envoye a Gemini. La reponse n’est utile que si elle peut etre retracee vers les chunks source, donc le contrat de sortie contient a la fois le texte et les citations.

Ce pattern est simple, mais il expose les vrais compromis RAG :

• Les petits chunks ameliorent la precision, mais peuvent perdre le contexte.
• Les grands chunks preservent le contexte, mais peuvent diluer la pertinence.
• Plus de chunks augmentent la couverture, mais aussi la taille du prompt.
• De bonnes citations augmentent la confiance, mais exigent une gestion stricte des metadonnees.

Stockage vectoriel

Pour le developpement local, ChromaDB suffisait. Il donnait un vector store pratique pour les embeddings et la recherche de similarite sans forcer trop tot le projet vers une infrastructure lourde.

Pour une vraie version de production, je serais plus attentif a la persistence, aux access patterns et au comportement operationnel. Une base managée avec support vectoriel, comme PostgreSQL avec pgvector, serait plus naturelle une fois l’assistant integre a un produit plus large.

Le point important est que le vector store est de la donnee derivee. Il peut etre reconstruit depuis le markdown source. Cela doit orienter le design :

• Versionner les documents source.
• Rendre l’ingestion repetable.
• Rendre la reindexation sure.
• Traiter le vector store comme une infrastructure jetable, pas comme la source de verite.

Reindexation

La documentation change, donc l’index doit changer avec elle.

Le projet inclut un endpoint de reindexation qui vide le vector store existant, rescane les fichiers markdown, regenere les embeddings et met a jour l’index consultable.

En production, je connecterais ce chemin au workflow de deploiement de la documentation pour que la connaissance de l’assistant reste alignee avec les docs publiees.

Forme de deploiement

La forme de deploiement compte parce qu’un assistant de documentation devient une partie de l’experience de documentation. Il a besoin d’une frontiere backend/frontend propre, d’une reindexation controlable, d’une gestion des secrets et d’assez d’observabilite pour distinguer les echecs de retrieval, prompt construction, generation modele ou contenu obsolete.

Sur Google Cloud, la forme naturelle serait :

• Cloud Run pour le backend FastAPI.
• Firebase Hosting ou un autre host statique pour MkDocs.
• Secret Manager pour les API keys.
• Cloud Build et Artifact Registry pour les builds container.
• Cloud Logging pour l’observabilite de base.

Ce que j’ai appris

Ce projet m’a fait voir RAG moins comme un pattern de prompt et plus comme un produit data. Le coeur du travail n’est pas “poser des questions a un modele sur des docs”. C’est maintenir un chemin fiable entre source, index derive et reponse generee.

Les lecons les plus utiles :

• La qualite du retrieval determine souvent la qualite de la reponse plus que le prompt.
• Le bon chunking est du design produit, pas seulement du traitement de texte.
• Les citations exigent une discipline de metadonnees des le debut.
• La reindexation fait partie du systeme.
• L’index vectoriel doit etre reproductible depuis les documents source.
• Un assistant de documentation doit avoir un comportement clair quand les docs ne contiennent pas la reponse.

Ce que j’ameliorerais ensuite

La prochaine version devrait renforcer evaluation et observabilite :

• Un petit jeu de questions de documentation avec sections source attendues.
• Des metriques de retrieval pour verifier si les bons chunks reviennent.
• Des checks LLM-as-a-judge pour groundedness et answer relevance.
• Du trace logging par requete pour separer retrieval, prompt construction et generation.
• Du feedback utilisateur sur l’utilite des reponses.
• Un fallback plus sur lorsque le contexte est insuffisant.

Liens du projet

• Repository GitHub : github.com/ThamuMnyulwa/mkdocs_rag
• Page portfolio : MkDocs RAG Documentation Assistant

Pensee finale

RAG est une frontiere de systeme, pas une fonctionnalite. Source content, chunking, embeddings, retrieval, prompt construction, generation, citation, evaluation et deploiement influencent tous la confiance que l’on peut accorder a l’assistant.

Quand ces pieces sont visibles et remplacables, l’architecture devient plus simple a operer et a ameliorer.