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)

[GN⁺]

Avis sur Hacker News

• Si la recherche basée sur le système de fichiers revient sur le devant de la scène, c’est parce qu’on redécouvre une forme de recherche sémantique non fondée sur les embeddings
  Comme un bibliothécaire range les livres par sujet sur des étagères, organiser les fichiers par domaine est plus interprétable
  C’est une méthode de recherche qui existe depuis longtemps, mais on ne redécouvre sa valeur que maintenant
  Article de blog connexe

  • La bibliothéconomie traditionnelle avait déjà capté des motifs profonds de la structure de l’information
    Le film de Pixar Ralph Wrecks The Internet illustre aussi bien ce concept
    Tweet de référence 1, Tweet de référence 2
  • Je travaille sur une base de code avec plus de 400 fichiers Python, et le RAG à base d’embeddings ramenait souvent des fragments de code hors sujet simplement parce que les mots se ressemblaient
    À la place, en laissant l’agent explorer directement l’arborescence des répertoires, il a compris la structure des modules en 30 secondes et a commencé à demander les bons fichiers
    J’avais oublié que la hiérarchie des répertoires était déjà un graphe de connaissances construit par des humains
  • En construisant un système de recherche pour LLM, j’ai fini par réinventer un index inversé (concordance)
    C’est le même concept que l’inverted index de Google, donc ce n’est pas vraiment nouveau
  • Quelqu’un a supposé que le RAG devait forcément utiliser la recherche vectorielle, et tout le monde semble avoir suivi ce courant
  • Au fond, un assistant IA est un personnage virtuel autocomplété par un LLM, donc des mécanismes interprétables, proches des interactions linguistiques humaines, sont plus avantageux

• Le RAG ne m’a pas donné de moyen de lire directement le contenu
  Donc maintenant, j’intègre les connaissances dans des pages statiques basées sur Markdown, puis après modification je génère des fichiers JSON afin que l’agent interroge cette source
  Lien d’explication

• L’affirmation selon laquelle la recherche par système de fichiers est meilleure que le RAG me semble confuse
  Une recherche par mots-clés comme grep est une ancienne approche, tandis que le RAG utilise la recherche vectorielle
  Mais dans une base de données, on peut indexer le contenu selon une hiérarchie, des tags ou une structure arbitraire
  La recherche peut combiner mots-clés, vecteurs, tf-idf, BM25 et bien d’autres méthodes
  Revenir au système de fichiers donne l’impression de régresser vers une technologie des années 1960

  • C’est vrai, mais dans la pratique les agents obtiennent de meilleures performances quand ils travaillent à partir de fichiers
    Les agents de code en CLI se comportent bien plus intelligemment lorsqu’ils ont un accès fichier
  • J’ai obtenu de bons résultats avec une recherche agentique basée sur une base de données
    Le point clé, c’est que l’agent peut exécuter lui-même diverses requêtes ad hoc
    Dans une base qui prend en charge à la fois les embeddings et la recherche plein texte, si l’agent peut interroger librement, c’est suffisamment agentique
  • En réalité, la plupart des systèmes de fichiers utilisent eux aussi en interne une structure de base de données
    Utiliser un système de fichiers comme une DB n’a rien de nouveau
  • J’ai l’impression que l’approche décrite dans l’article revient finalement à cela
  • Je pense qu’il vaut mieux laisser l’agent explorer directement plusieurs sources de données

• Le calcul selon lequel 850 000 conversations par mois coûteraient plus de 70 000 dollars par an semble étrange
  Je me demandais où passaient autant de CPU et de mémoire, puis j’ai vu que cela venait de ChromaFs de Vercel Labs, basé sur just-bash

  • Si on donne à chaque agent un conteneur isolé, la mémoire reste occupée même quand il ne se passe rien, ce qui fait grimper les coûts

• J’apprécie cette renaissance des applications CLI
  J’ai créé un système de fichiers virtuel qui reflète le vrai système de fichiers du Mac avec FUSE, afin de limiter l’agent à cette arborescence uniquement
  J’ai un agent persistant par dépôt, et les autorisations sont contrôlées par le système de fichiers virtuel
  Projet bashguard

• Nous utilisons à la fois un système de fichiers virtuel (VFS) et le RAG
  Le cœur du RAG, c’est la qualité des données : on découpe les documents en unités de sens et on génère des métadonnées et des liens
  Avec voyage contextual embedding, on embed chaque chunk avec son document
  Lors de la recherche, l’agent peut suivre les liens ou analyser le texte source
  La qualité du reranking a un impact majeur sur les performances

  • Notre VFS est basé sur Postgres et projeté sous forme de fichiers/répertoires
    Il prend en charge grep, bm25, jq, des outils d’aperçu, etc., et fonctionne au-dessus de Pydantic AI

• Émuler un shell POSIX en TypeScript pour faire de la recherche hiérarchique ressemble à de la sur-ingénierie
  À chaque exécution de ls ou grep, on ajoute un cycle d’inférence, ce qui augmente la latence

  • Si on monte FUSE au-dessus des chunks, il ne devrait pas être nécessaire d’émuler un shell

• Je ne connais pas bien la stack technique, mais je me demandais pourquoi ils avaient tenu à créer un faux shell
  Une solution FUSE paraît plus naturelle

  • Ils ont bien envisagé un adaptateur FUSE, mais c’était beaucoup trop lent
    Ils n’avaient pas besoin d’une compatibilité POSIX complète et ne faisaient que de l’exploration de documents en lecture seule
    Il était donc plus simple de ne prendre en charge qu’une partie des commandes bash

• Dans ce contexte où l’on rend les documents accessibles via des outils de système de fichiers, le SDK IA de Vercel est intéressant
  Ils incluent des documents .mdx à la racine du package npm, pour inciter l’agent à faire d’abord un grep dans la documentation locale
  Exemple de SKILL.md

• C’est une bonne approche pour des startups comme Mintlify, mais dans des organisations complexes, cela peut être moins pratique
  Quand la structure n’est pas hiérarchique ou que la documentation est mélangée, le RAG peut être plus utile

  • Ici, il y a un cas d’usage clair, la recherche dans le code, donc c’est simple
    Le RAG n’est pas universel, et l’équipe Claude Code est arrivée à la même conclusion
  • Comme la technologie OCR a suffisamment progressé, cette approche pourrait aussi être généralisée si les documents sont exploitables par OCR
  • Si on superpose un VFS à une organisation documentaire complexe, cela ne reste au fond qu’une variante d’indexeur, et sans contrôle d’accès, cela pose des problèmes de sécurité