Aufbau eines virtuellen Dateisystems als RAG-Alternative für einen KI-Dokumentenassistenten

• Um die Grenzen der bisherigen RAG-basierten Suche zu überwinden, wurde auf eine virtuelle Dateisystemstruktur umgestellt, in der Dokumente aus Dateien und Verzeichnissen bestehen
• Mit ChromaFs wurde eine Lösung implementiert, die auf der Chroma-Datenbank basiert und Befehle wie grep, cat, ls und find ohne tatsächliches Kopieren von Dateien ausführen kann
• Dadurch wurde die Zeit zur Sitzungserstellung von 46 Sekunden auf 100 Millisekunden verkürzt, während die zusätzlichen Rechenkosten auf nahe 0 Dollar sanken
• Die Zugriffskontrolle erfolgt über RBAC-Filterung anhand von Dateipfad-Metadaten, sodass keine separaten Container oder die Verwaltung von Benutzergruppen erforderlich sind
• Dadurch kann der Mintlify-Dokumentenassistent letztlich als großskaliger Dienst mit sofortiger Antwort, niedrigen Kosten und zustandsloser Architektur betrieben werden

---

Ein virtueller Dateisystemansatz jenseits der Grenzen von RAG

• Die bisherige RAG-basierte Dokumentensuche gab nur Textausschnitte zurück, die zur Abfrage passten, wodurch Antworten über mehrere Seiten hinweg oder eine präzise Phrasensuche schwierig waren
• Um das zu lösen, wurde die Dokumentstruktur in eine wie ein Dateisystem durchsuchbare Form überführt: Jede Dokumentseite wird einer Datei, jeder Abschnitt einem Verzeichnis zugeordnet
• Der Agent kann Dokumente direkt über die Befehle grep, cat, ls und find durchsuchen, sodass eine Struktur entsteht, in der sich Dokumente ähnlich wie eine Codebasis durchsuchen lassen

Das Container-Engpassproblem

• Der übliche Ansatz besteht darin, für den Agenten ein echtes Dateisystem bereitzustellen, indem eine isolierte Sandbox-Umgebung erzeugt und das Repository geklont wird
• Bei Frontend-Assistenten führt das jedoch zu erheblichen Verzögerungen bei der Sitzungserstellung; die p90-Zeit für die Sitzungserstellung liegt bei etwa 46 Sekunden
• Bei 850.000 Konversationen pro Monat entstehen selbst bei einer Minimalkonfiguration (1 vCPU, 2GiB RAM, 5 Minuten Sitzungsdauer) jährliche Infrastrukturkosten von über 70.000 Dollar
• Um diesen Engpass zu beseitigen, wurde ein virtuelles Dateisystem benötigt, das sofort reagiert und kostengünstig arbeitet

Implementierung einer virtuellen Shell — ChromaFs

• Anstelle eines echten Dateisystems wird nur die Illusion eines virtuellen Dateisystems bereitgestellt
• Da die bestehenden Dokumentdaten bereits in der Chroma-Datenbank indexiert waren, wurde darauf aufbauend ChromaFs entwickelt
• ChromaFs fängt UNIX-Befehle ab und wandelt sie in Chroma-Abfragen um
• Dadurch wurde die Zeit zur Sitzungserstellung von 46 Sekunden auf 100 Millisekunden verkürzt, während die zusätzlichen Rechenkosten auf nahe 0 Dollar sanken

Metric	Sandbox	ChromaFs
P90 Boot Time	~46 Sekunden	~100ms
Marginal Compute Cost	~$0.0137/Konversation	~$0
Search Mechanism	Festplatten-Scan	DB-Metadatenabfrage
Infrastructure	Externe Sandbox wie Daytona	Wiederverwendung der bestehenden DB

• Implementiert auf Basis von just-bash (Vercel Labs), mit Unterstützung für die Befehle grep, cat, ls, find, cd
• Unter Nutzung des IFileSystem-Interfaces von just-bash bleiben Pipe-Verarbeitung und Flag-Logik unverändert, während Dateizugriffe in Chroma-Abfragen umgewandelt werden

Bootstrapping des Verzeichnisbaums

• ChromaFs muss vor der Ausführung wissen, welche Dateien existieren, daher wird der vollständige Dateibaum in der Chroma-Collection als komprimiertes JSON (__path_tree__) gespeichert
• Bei der Serverinitialisierung wird dieser geladen und in zwei In-Memory-Strukturen rekonstruiert
  • Set<string> der Dateipfade
  • Map<string, string[]> mit den Kind-Elementen je Verzeichnis
• Danach können ls, cd und find ohne Netzwerkaufrufe sofort im lokalen Speicher verarbeitet werden; nachfolgende Sitzungen derselben Site verwenden den zwischengespeicherten Baum erneut

Zugriffskontrolle

• Der Pfadbaum enthält die Felder isPublic und groups, und auf Basis des Sitzungstokens des Nutzers bleiben nur die zugänglichen Dateien erhalten
• Dateien ohne Zugriffsberechtigung werden vollständig aus dem Baum entfernt, sodass der Agent den betreffenden Pfad nicht erkennen kann
• In bisherigen Sandboxen mussten dafür Linux-Benutzergruppen, chmod und Container-Isolation verwaltet werden; in ChromaFs lässt sich RBAC allein mit einfacher Filterlogik umsetzen

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	✗

Wiederzusammensetzen von Dokumentfragmenten

• In Chroma gespeicherte Dokumente sind für Embeddings in mehrere Fragmente aufgeteilt
• Bei cat /auth/oauth.mdx werden alle Fragmente mit demselben page-Slug geladen, nach chunk_index sortiert und anschließend zusammengeführt
• Das Ergebnis wird zwischengespeichert, sodass selbst in wiederholten grep-Workflows keine erneute DB-Abfrage nötig ist
• Große OpenAPI-Spezifikationen usw. werden als Lazy-Loading-Pointer (lazy file pointer) registriert und erst beim Zugriff aus S3 geladen
• Alle Schreiboperationen geben den Fehler EROFS (schreibgeschütztes Dateisystem) zurück und erhalten so eine sichere, zustandslose Struktur

Grep-Optimierung

• Da der Befehl grep -r bei einfachem Netzwerkscannen sehr langsam wäre, wurde er mit einer zweistufigen Filterstruktur optimiert
  • Stufe 1: Auswahl von Kandidatendateien mittels Chroma-Abfragen ($contains, $regex)
  • Stufe 2: Vorab-Laden in den Redis-Cache und anschließend präzise In-Memory-Filterung in just-bash
• Dadurch lassen sich auch große rekursive Suchen im Millisekundenbereich abschließen

Fazit

• ChromaFs treibt den Mintlify-Dokumentenassistenten an, der täglich über 30.000 Vorgänge und Hunderttausende Nutzer bedient
• Durch den Ersatz von Sandboxen wurden sofortige Sitzungserstellung, nahezu 0 Zusatzkosten, integriertes RBAC und eine zustandslose Architektur erreicht
• Direkt in allen Dokumentationssites von Mintlify nutzbar (mintlify.com/docs)

[GN⁺]

Hacker-News-Kommentare

• Der Grund, warum dateisystembasierte Suche wieder Beachtung findet, ist, dass wir eine Form der semantischen Suche ohne Embeddings wiederentdecken
  So wie ein Bibliothekar Bücher nach Themen in Regale einsortiert, ist ein nach Domänen organisierter Dateiaufbau besser interpretierbar
  Diese Suchmethode gibt es schon lange, aber erst jetzt wird ihr Wert wieder erkannt
  Zugehöriger Blogbeitrag

  • Die traditionelle Bibliothekswissenschaft hat die tiefen Muster von Informationsstrukturen bereits erfasst
    Auch in Pixars Ralph Wrecks The Internet wurde dieses Konzept gut dargestellt
    Referenz-Tweet 1, Referenz-Tweet 2
  • Ich arbeite an einer Codebasis mit über 400 Python-Dateien, und embedding-basiertes RAG hat oft irrelevante Codeschnipsel geholt, nur weil die Wörter ähnlich waren
    Als ich den Agenten stattdessen den Verzeichnisbaum direkt durchsuchen ließ, verstand er in 30 Sekunden die Modulstruktur und begann, die richtigen Dateien anzufordern
    Ich hatte vergessen, dass die Verzeichnishierarchie selbst bereits ein von Menschen gebauter Wissensgraph war
  • Beim Bau eines LLM-Suchsystems habe ich am Ende die inversen Indizes (concordance) neu erfunden
    Das ist dasselbe Konzept wie Googles inverted index und also eigentlich nichts völlig Neues
  • Irgendjemand hat wohl angenommen, dass RAG zwingend Vektorsuche verwenden muss, und alle sind diesem Trend gefolgt
  • AI-Assistenten sind letztlich virtuelle Figuren, die vom LLM autovervollständigt werden, daher sind interpretierbare Mechanismen wie in menschlicher sprachlicher Interaktion vorteilhafter

• RAG hat mir keine Möglichkeit gegeben, Inhalte direkt zu lesen
  Deshalb konsolidiere ich Wissen jetzt in statischen Markdown-Seiten und baue nach Änderungen eine JSON-Datei, die der Agent als Quelle abfragt
  Erklärungslink

• Die Behauptung, Dateisystemsuche sei besser als RAG, ist verwirrend
  Keyword-Suche wie mit grep ist ein alter Ansatz, RAG nutzt Vektorsuche
  In Datenbanken kann man Inhalte aber über Hierarchien, Tags und beliebige Strukturen indizieren
  Suche kann mit Keywords, Vektoren, tf-idf, BM25 und verschiedenen Kombinationen davon arbeiten
  Zum Dateisystem zurückzugehen wirkt wie ein Rückfall auf Technik aus den 60ern

  • Das stimmt, aber in der Praxis funktionieren Agenten dateibasiert oft besser
    CLI-basierte Coding-Agenten verhalten sich bei Dateizugriffen deutlich klüger
  • Ich habe mit datenbankbasierter agentic search gute Ergebnisse erzielt
    Entscheidend ist, dass der Agent verschiedene ad-hoc-Abfragen selbst ausführen kann
    Wenn der Agent in einer DB frei abfragen kann, die sowohl Embeddings als auch Volltextsuche unterstützt, ist das ausreichend agentisch
  • Tatsächlich verwenden die meisten Dateisysteme intern ebenfalls Datenbankstrukturen
    Ein Dateisystem wie eine DB zu nutzen, ist nichts Neues
  • Ist das am Ende nicht genau der Ansatz, von dem im Artikel die Rede ist?
  • Ich denke, es ist besser, den Agenten mehrere Datenquellen direkt erkunden zu lassen

• Die Rechnung, dass 850.000 Gespräche pro Monat mehr als 70.000 Dollar pro Jahr kosten sollen, klingt seltsam
  Ich habe mich gefragt, wofür so viel CPU und Speicher verbraucht werden, und der Grund war ChromaFs von Vercel Labs auf just-bash-Basis

  • Wenn man jedem Agenten einen isolierten Container gibt, bleibt selbst im Leerlauf Speicher belegt, was die Kosten stark erhöht

• Ich genieße gerade die Renaissance von CLI-Anwendungen
  Ich habe mit FUSE ein virtuelles Dateisystem gebaut, das das echte Dateisystem meines Macs spiegelt, und beschränke den Agenten auf genau diesen Baum
  Für jedes Repo läuft ein langlebiger Agent, und die Berechtigungen werden über das virtuelle Dateisystem gesteuert
  Projekt bashguard

• Wir verwenden sowohl virtuelle Dateisysteme (VFS) als auch RAG
  Der Kern von RAG ist die Datenqualität: Dokumente werden in semantische Einheiten zerlegt und mit Metadaten und Links versehen
  Mit voyage contextual embedding wird jeder Chunk zusammen mit dem Dokument eingebettet
  Bei der Suche kann der Agent Links folgen oder das Original analysieren
  Die Reranking-Qualität hat großen Einfluss auf die Leistung

  • Unser VFS ist Postgres-basiert und wird als Datei-/Verzeichnisstruktur projiziert
    Es unterstützt grep, bm25, jq, Vorschauwerkzeuge und läuft auf Pydantic AI

• Eine POSIX-Shell in TypeScript zu emulieren, um hierarchische Suche zu ermöglichen, wirkt wie Overengineering
  Jedes Ausführen von ls oder grep erhöht die Anzahl der Inferenzzyklen und damit die Latenz

  • Wenn man FUSE über die Chunks legt, wäre eine Shell-Emulation vermutlich nicht nötig

• Ich kenne den Technologie-Stack nicht gut, aber ich habe mich gefragt, warum man überhaupt eine Fake-Shell gebaut hat
  Eine FUSE-Lösung wirkt natürlicher

  • Ein FUSE-Adapter wurde tatsächlich erwogen, war aber zu langsam
    Vollständige POSIX-Kompatibilität war nicht nötig, es ging nur um schreibgeschützte Dokumentenerkundung
    Deshalb war es einfacher, nur einen Teil der bash-Befehle zu unterstützen

• Im Kontext, Dokumente über Dateisystem-Werkzeuge zugänglich zu machen, ist Vercels AI SDK interessant
  Es enthält .mdx-Dokumentation im Root des npm-Pakets, damit der Agent zuerst in lokaler Dokumentation mit grep sucht
  SKILL.md-Beispiel

• Für Startups wie Mintlify ist das ein guter Ansatz, in komplexen Organisationen könnte es aber weniger praktikabel sein
  In Umgebungen mit nicht-hierarchischen Strukturen oder vermischter Dokumentation ist RAG nützlicher

  • Hier gibt es mit Codesuche einen klaren Use Case, daher ist es einfacher
    RAG ist keine Universallösung, und auch das Claude-Code-Team ist zu demselben Schluss gekommen
  • Da sich OCR-Technologie stark verbessert hat, ließe sich dieser Ansatz auch verallgemeinern, sofern die Dokumente per OCR erschließbar sind
  • Wenn man VFS über eine komplexe Dokumentenorganisation legt, ist es am Ende nur eine Variante eines Indexers, und ohne Zugriffskontrolle entstehen Sicherheitsprobleme