pguso/rag-from-scratch: RAG als Lehrbuch in JavaScript, nicht als Framework

Ein Lehrbuch statt einer Bibliothek

Das Repository beschreibt sich selbst als Antwort auf die Frage, wie Retrieval-Augmented Generation intern funktioniert. Der Einstiegssatz lautet, das Projekt wolle RAG entmystifizieren, indem man es selbst baut. Der Aufbau folgt dieser Absicht: Jedes Verzeichnis unter examples/ behandelt einen Schritt der Pipeline und enthält drei Dateien, example.js, CODE.md und CONCEPT.md. Die Trennung ist bewusst. CODE.md erklärt den Code, CONCEPT.md den Hintergrund, und example.js bleibt schlank genug, um es in einem Durchgang zu lesen. Das erste Beispiel, 00_how_rag_works, verspricht laut README einen vollständigen RAG-Ablauf in unter 70 Zeilen. Wer nach einem npm-Paket sucht, das er in eine bestehende Anwendung einhängt, wird hier nicht fündig. Wer dagegen schon einmal eine Vektordatenbank benutzt hat, ohne zu wissen, was beim Chunking passiert, findet die fehlende Schicht.

Die zehnstufige Pipeline und was sie verschweigt

Die Konzeptübersicht listet zehn Schritte: Knowledge Requirements, Data Loading, Text Splitting, Embedding, Vector Store, Retrieval, Post-Retrieval Re-Ranking, Query Preprocessing und Embedding Normalization, Augmentation, Generation. Diese Reihenfolge ist die eigentliche Lehre des Projekts. Schritt 1, die Definition der Wissensanforderungen, steht vor jeder Zeile Code, und das ist in den meisten RAG-Tutorials der übersprungene Teil. Schritt 7, das Re-Ranking, ist in der Konzeptliste aufgeführt, taucht aber in der im README sichtbaren Lernpfad-Liste nicht als eigenes Beispiel auf. Wer den Lernpfad von 0 bis 9 durchgeht, sollte prüfen, ob das Re-Ranking in einem späteren, im README abgeschnittenen Abschnitt behandelt wird. Auffällig ist außerdem die Nummerierung: Auf Beispiel 1 folgt im Lernpfad direkt 2, aber der Ordner für Data Loading heißt 02_data_loading, während How RAG Works unter 00_how_rag_works liegt. Die Nummern im Text und im Dateipfad stimmen also nicht durchgehend überein. Das ist kein Fehler mit Folgen, aber wer nach Dateipfaden navigiert, sollte sich an den Pfaden orientieren, nicht an der Nummerierung im Fließtext.

Chunking, Embeddings und der In-Memory-Store

Die Beispiele 2 und 3 behandeln das Aufteilen von Text. Das README nennt als Schlüsselbegriffe chunking logic, context windows und granularity trade-offs, also die Abwägung zwischen groben und feinen Abschnitten. Genau hier liegt der Teil, der in fertigen Frameworks hinter Konfigurationsparametern verschwindet. Beispiel 4 erzeugt Embeddings lokal, Beispiel 5 speichert sie in einem In-Memory-Store und zeigt laut README, wie Nearest-Neighbor-Suche funktioniert. Der Ordnerpfad lautet examples/05_building_vector_store/01_in_memory_store/. Das 01 im Namen deutet an, dass weitere Store-Varianten vorgesehen oder vorhanden sind; aus dem vorliegenden Material lässt sich das nicht bestätigen. Wer den Store produktiv nutzen will, sollte wissen, dass ein In-Memory-Index mit dem Prozess endet. Persistenz, gleichzeitiger Zugriff und Wiederaufbau nach einem Neustart sind Themen, die ein solches Beispiel naturgemäß ausklammert. Das ist keine Schwäche des Lehransatzes, aber es ist die Grenze, an der man von diesem Repository zu einem anderen Werkzeug wechselt.

Retrieval-Strategien: von top-k bis Reciprocal Rank Fusion

Ab Beispiel 6 wird es interessanter als in den meisten Einführungen. Zuerst die einfache Variante in 06_retrieval_strategies/01_basic_retrieval/, mit top-k-Abruf und Ähnlichkeitsbewertung. Danach Query Preprocessing in 02_query_preprocessing/, wo Stopword-Entfernung und Normalisierung vor dem Embedding passieren. Das ist ein Detail, das viele übersehen: Wenn die Anfrage anders aussieht als die indexierten Chunks, leidet die Ähnlichkeit, auch wenn das Modell gut ist. Beispiel 8 kombiniert Vektor- und Keyword-Suche unter dem Stichwort Hybrid Search, mit BM25 plus Embeddings und gewichteter Bewertung. Beispiel 9 geht weiter und zerlegt eine komplexe Anfrage in Teilfragen, führt sie parallel aus und fusioniert die Ergebnislisten. Das README nennt dafür Reciprocal Rank Fusion, gewichtete Fusion und Deduplizierung. RRF ist bemerkenswert praktisch, weil sie Ranglisten kombiniert, ohne die Rohscores der einzelnen Verfahren vergleichen zu müssen. Dass ein Lehrprojekt diesen Schritt zeigt, statt bei Cosine Similarity zu enden, ist der stärkste Teil des Curriculums.

Lokale Modelle und die Frage der Reproduzierbarkeit

Das Repository setzt auf lokale LLMs, das Topic node-llama-cpp verweist auf die Anbindung. Der Vorteil liegt auf der Hand: keine API-Schlüssel, keine laufenden Kosten pro Anfrage, keine Daten, die das eigene Rechner verlassen. Der Preis ist ebenfalls klar. Die Qualität der generierten Antwort hängt an dem Modell, das man lokal laufen lässt, und die Beispiele dürften mit einem kleinen Modell andere Ergebnisse liefern als mit einem großen. Das README macht dazu keine Angaben, und aus dem vorliegenden Material geht nicht hervor, welches Modell oder welche Modellgröße die Beispiele erwarten. Wer die Beispiele nachvollzieht, sollte deshalb damit rechnen, dass die Ausgaben von den im Text beschriebenen abweichen. Das ist bei lokalem Betrieb normal und kein Zeichen dafür, dass etwas falsch konfiguriert ist. Es bedeutet nur, dass man die Ähnlichkeitswerte und die abgerufenen Chunks prüfen sollte, nicht die Formulierung der finalen Antwort.

Inbetriebnahme: Node, Beispiele, Reihenfolge

Das Repository enthält laut Beschreibung keine Releases. Es gibt also keine versionierten Artefakte, an denen man sich festhalten könnte, sondern nur den Branch main. Der Einstieg läuft über die Beispiele: Man klont das Repository, wechselt in ein Verzeichnis unter examples/ und führt die jeweilige example.js mit Node aus. Für die Embedding- und Generierungsschritte ist node-llama-cpp erforderlich, das als Topic genannt wird und Modelldateien im lokalen Dateisystem erwartet. Konkrete Kommandozeilen, etwa ein npm install oder ein Modell-Download-Befehl, sind im vorliegenden README-Ausschnitt nicht enthalten. Wer startet, sollte deshalb zuerst die CODE.md des gewünschten Beispiels lesen, weil dort die Ausführung beschrieben sein dürfte. Die Reihenfolge im Lernpfad ist nicht beliebig: Beispiel 5 setzt Embeddings aus Beispiel 4 voraus, Beispiel 6 einen gefüllten Store. Quereinstieg in Beispiel 9 ohne die vorherigen Schritte führt zu fehlenden Datenstrukturen, nicht zu einem Verständnisgewinn.

Wann dieses Repository das falsche Werkzeug ist

Der In-Memory-Store aus Beispiel 5 skaliert nicht über den Arbeitsspeicher eines Prozesses hinaus. Es gibt laut README keinen Hinweis auf Persistenz, auf inkrementelles Nachindexieren oder auf einen Server, der Abfragen von mehreren Clients bedient. Für einen Prototyp mit einigen hundert Chunks reicht das. Für einen Korpus, der regelmäßig wächst, braucht man einen Vektorindex, der Aktualisierungen ohne vollständigen Neuaufbau verkraftet. Ein zweiter Punkt: Das Repository versteht sich als Lernmaterial, nicht als laufend gepflegte Abhängigkeit. Es gibt keine Releases, also auch keine Versionsnummer, gegen die man prüfen könnte, ob sich das Verhalten zwischen zwei Ständen geändert hat. Wer das Projekt als Grundlage für eigenen Produktivcode nimmt, kopiert Beispielcode ohne Support-Zusage. Das ist legitim, aber man sollte es wissen. Der letzte Commit liegt laut Repository-Metadaten im März 2026, das Projekt ist nicht archiviert.

Was man stattdessen nimmt und worin der Unterschied liegt

Als Alternative bietet sich LangChain.js an, das dieselben Bausteine als Bibliothek bereitstellt: Loader, Splitter, Vektorspeicher-Anbindungen, Retriever und Ketten. Der Unterschied liegt nicht im Funktionsumfang, sondern in der Richtung der Abstraktion. LangChain.js gibt einem eine Schnittstelle, hinter der mehrere Implementierungen austauschbar sind, und man konfiguriert, welche. rag-from-scratch gibt einem eine Implementierung, die man liest und verändert, ohne dass eine Fassade dazwischen liegt. Wer die Bibliothek nutzt, muss die Chunking-Strategie über Parameter steuern und deren Wirkung indirekt erschließen. Wer das Lehr-Repository nutzt, sieht die Schleife, die die Chunks bildet. Der zweite Ansatz ist langsamer und führt zu Code, den man selbst warten muss. Der erste ist schneller und führt zu Code, dessen Verhalten man über Dokumentation versteht. Beide Wege sind legitim, aber sie passen zu unterschiedlichen Ausgangslagen.

Lizenz, Wartung und der Aufwand danach

Das Repository steht unter der MIT-Lizenz. Das erlaubt Weitergabe und Veränderung, auch in kommerziellen Projekten, solange der Urheberrechtshinweis und der Lizenztext erhalten bleiben. Wer Code aus den Beispielen übernimmt, sollte diesen Hinweis mitführen. Rechtliche Beratung ist das nicht, und bei einer Übernahme in ein Produkt gehört die Lizenzfrage ohnehin in die Prüfung, die das eigene Haus vorsieht. Zum Wartungsaufwand lässt sich aus dem Material wenig sagen: keine Releases, keine Changelogs im Auszug, nur ein aktiver Branch. Das bedeutet für Nutzer, dass Upgrades nicht als Versionssprung anfallen, sondern als Diff im Repository. Wer die Beispiele als Lernpfad durcharbeitet und danach eine eigene Pipeline baut, trägt die Wartung dieser Pipeline selbst. Das Lehr-Repository selbst verursacht keine laufenden Kosten außer Rechenzeit für lokale Modelle und Speicherplatz für die Modelldateien.

Redaktionelles Fazit

Wer RAG für eine produktive Anwendung braucht, sollte zu einer ausgereiften Bibliothek oder einem Vektordienst greifen; rag-from-scratch ist Lehrmaterial und in dieser Rolle sehr brauchbar. Vor dem Einstieg lohnt es sich, die Datei examples/05_building_vector_store/01_in_memory_store/CODE.md zu lesen, um zu sehen, wie der In-Memory-Store aufgebaut ist, und parallel einen Blick auf den Stand des letzten Commits zu werfen, weil es keine Releases gibt, an denen man sich orientieren könnte.

Offizielle Quellen

1. Issues
2. License: MIT
3. pguso/rag-from-scratch on GitHub
4. README