Créer un système de fichiers virtuel comme alternative au RAG pour un assistant documentaire IA

• Pour dépasser les limites de la recherche basée sur le RAG, l’approche a été remplacée par une structure de système de fichiers virtuel où les documents sont organisés en fichiers et répertoires
• ChromaFs a été implémenté sur la base de la base de données Chroma, ce qui permet d’exécuter les commandes grep, cat, ls et find sans dupliquer les fichiers réels
• Avec cette méthode, le temps de création de session est passé de 46 secondes à 100 millisecondes, et le coût de calcul additionnel a chuté à un niveau proche de 0 dollar
• Le contrôle d’accès est géré par un filtrage RBAC des métadonnées de chemin de fichier, ce qui évite d’avoir à gérer des conteneurs séparés ou des groupes d’utilisateurs
• Au final, l’assistant documentaire de Mintlify peut être exploité à grande échelle avec une architecture à réponse immédiate, à faible coût et sans état

---

Une approche par système de fichiers virtuel au-delà des limites du RAG

• La recherche documentaire basée sur le RAG renvoyait uniquement des fragments de texte correspondant à la requête, ce qui compliquait les réponses couvrant plusieurs pages ou les recherches de formulations exactes
• Pour y remédier, la structure documentaire a été transformée en une forme navigable comme un système de fichiers, en associant chaque page de documentation à un fichier et chaque section à un répertoire
• L’agent peut explorer directement les documents avec les commandes grep, cat, ls et find, dans une architecture pensée pour rechercher dans la documentation comme un développeur parcourt une base de code

Le goulot d’étranglement des conteneurs

• L’approche classique consiste à fournir à l’agent un véritable système de fichiers en créant un environnement sandbox isolé et en y clonant le dépôt
• Mais, dans un assistant frontend, la latence de création de session devenait critique, avec un temps de création de session p90 d’environ 46 secondes
• Sur la base de 850 000 conversations par mois, même avec une configuration minimale (1 vCPU, 2 GiB de RAM, session maintenue 5 minutes), cela représentait plus de 70 000 dollars de coûts d’infrastructure par an
• Pour supprimer ce goulot d’étranglement, il fallait un système de fichiers virtuel capable de répondre immédiatement et de fonctionner à faible coût

Implémentation du shell virtuel — ChromaFs

• Au lieu d’un véritable système de fichiers, seule une illusion de système de fichiers virtuel est fournie
• Les données documentaires existantes étant déjà indexées dans la base de données Chroma, ChromaFs a été construit sur cette base
• ChromaFs intercepte les commandes UNIX et les convertit en requêtes Chroma
• Résultat : le temps de création de session est passé de 46 secondes à 100 millisecondes, et le coût de calcul additionnel est tombé à un niveau proche de 0 dollar

Metric	Sandbox	ChromaFs
P90 Boot Time	~46 secondes	~100ms
Marginal Compute Cost	~$0.0137/conversation	~$0
Search Mechanism	scan disque	requêtes de métadonnées DB
Infrastructure	sandbox externe comme Daytona	réutilisation de la DB existante

• L’implémentation repose sur just-bash (Vercel Labs) et prend en charge les commandes grep, cat, ls, find et cd
• En s’appuyant sur l’interface IFileSystem de just-bash, la logique de traitement des pipes et des flags reste inchangée, tandis que les appels d’accès aux fichiers sont convertis en requêtes Chroma

Amorçage de l’arborescence des répertoires

• Comme ChromaFs doit savoir quels fichiers existent avant l’exécution, l’arborescence complète est stockée dans une collection Chroma sous forme de JSON compressé (__path_tree__)
• Lors de l’initialisation du serveur, celle-ci est restaurée dans deux structures mémoire
  • un Set<string> des chemins de fichiers
  • une Map<string, string[]> de la liste des enfants par répertoire
• Ensuite, les commandes ls, cd et find sont traitées instantanément en mémoire locale sans appel réseau, et les sessions suivantes sur le même site réutilisent l’arborescence mise en cache

Contrôle d’accès

• L’arborescence de chemins inclut les champs isPublic et groups, et seuls les fichiers accessibles selon le jeton de session utilisateur sont conservés
• Les fichiers sans autorisation d’accès sont entièrement supprimés de l’arborescence, de sorte que l’agent ne peut même pas reconnaître leur existence
• Dans les sandboxes traditionnelles, cela nécessitait de gérer les groupes d’utilisateurs Linux, chmod ou l’isolation par conteneur ; avec ChromaFs, le RBAC est implémenté par une simple logique de filtrage

Path	Access	Visible
/auth/oauth.mdx	public	✓
/auth/api-keys.mdx	public	✓
/internal/billing.mdx	admin, billing	✗
/api-reference/users.mdx	public	✓
/api-reference/payments.mdx	billing	✗

Réassemblage des fragments documentaires

• Les documents stockés dans Chroma sont découpés en plusieurs fragments pour les embeddings
• Lors de l’exécution de cat /auth/oauth.mdx, tous les fragments partageant le même slug page sont récupérés, triés selon chunk_index, puis fusionnés
• Le résultat est mis en cache, ce qui évite toute nouvelle interrogation de la base même dans des workflows grep répétés
• Les grands fichiers comme les spécifications OpenAPI volumineuses sont enregistrés comme pointeurs de fichiers chargés à la demande (lazy file pointer), et ne sont récupérés depuis S3 qu’au moment de l’accès
• Toutes les opérations d’écriture renvoient une erreur EROFS (système de fichiers en lecture seule), ce qui permet de conserver une architecture sûre sans état (stateless)

Optimisation de grep

• La commande grep -r est très lente si elle repose sur un simple balayage réseau ; elle a donc été optimisée avec une structure de filtrage en deux étapes
  • Étape 1 : sélection des fichiers candidats à l’aide de requêtes Chroma ($contains, $regex)
  • Étape 2 : préchargement dans le cache Redis, puis filtrage fin en mémoire dans just-bash
• Grâce à cela, même les recherches récursives à grande échelle peuvent être traitées en quelques millisecondes

Conclusion

• ChromaFs fait fonctionner l’assistant documentaire de Mintlify, utilisé pour plus de 30 000 requêtes par jour par plusieurs centaines de milliers d’utilisateurs
• En remplaçant les sandboxes, il permet une création de session immédiate, un coût additionnel proche de 0, un RBAC intégré et une architecture sans état
• Il peut être utilisé directement sur tous les sites de documentation de Mintlify (mintlify.com/docs)