bRAG-langchain: ein Notebook-Kurs für eigene RAG-Pipelines

Fünf Notebooks statt einer Bibliothek

Das Repository liefert keine installierbare Abhängigkeit, sondern eine Abfolge von Jupyter-Notebooks unter notebooks/. Die README beschreibt sie als hands-on guides, die von einer Einführung bis zu Multi-Querying und eigenen RAG-Bauten reichen. Wer eine Pipeline sucht, die er per pip einbindet, wird hier nicht fündig. Wer verstehen will, wie Retrieval, Reranking und Query-Erzeugung zusammenspielen, findet dagegen einen Pfad, der bei einer Baseline beginnt und bei ColBERT endet.

Die Zielgruppe ist damit enger, als der Titel vermuten lässt. Angesprochen sind Entwickler, die bereits Python schreiben und LangChain zumindest grob kennen. Die Notebooks dienen als Vorlage, aus der ein eigenes Projekt herausgeschnitten wird. Die README nennt für diesen Einstieg ausdrücklich full_basic_rag.ipynb als boilerplate starter code eines anpassbaren RAG-Chatbots. Das ist der praktisch relevanteste Satz der ganzen Datei.

Wie die Retrieval-Kette in den Notebooks aufgebaut ist

Die Architektur folgt dem üblichen Ablauf: Dokumente laden, in Chunks zerlegen, Embeddings erzeugen, in einem Vektorspeicher ablegen, ähnliche Passagen abrufen und zusammen mit der Frage an ein Sprachmodell geben. Die README zeigt dieses Muster als Architekturbild unter assets/img/rag-architecture.png und beschreibt es im ersten Notebook als Basic RAG Pipeline.

Interessanter sind die Abweichungen davon. Das zweite Notebook erzeugt mehrere Suchanfragen aus einer Frage, um die Trefferliste zu streuen. Das dritte klassifiziert eingehende Fragen, bevor überhaupt gesucht wird: logisches Routing ordnet sie anhand von Funktionen einer Datenquelle zu, semantisches Routing entscheidet per Embedding und Kosinusähnlichkeit, ob eine Frage an einen Mathe- oder einen Physik-Prompt geht. Zusätzlich definiert es ein strukturiertes Suchschema für YouTube-Metadaten, sodass Filter wie Aufrufzahl oder Veröffentlichungsdatum als Abfrage formuliert werden können.

Das vierte Notebook trennt Repräsentationen voneinander. Ein MultiVectorRetriever hält mehrere Vektorformen desselben Dokuments, Zusammenfassungen liegen laut README in einem InMemoryByteStore neben den übergeordneten Dokumenten. RAPTOR und ColBERT werden behandelt, letzteres mit einem Wikipedia-Beispiel zu Hayao Miyazaki. Das fünfte Notebook schließt mit Reciprocal Rank Fusion, Cohere-Reranking sowie Verweisen auf CRAG und Self-RAG.

Auffällig ist der Umgang mit Tiefe. RAPTOR und CRAG werden nicht ausimplementiert, sondern über Links zu externen Ressourcen erschlossen. Wer erwartet, dass jedes Stichwort im Titel auch Code im Notebook hat, wird an diesen Stellen enttäuscht.

Installation: Python 3.11.11 ist keine Empfehlung, sondern Bedingung

Die README legt Python 3.11.11 als preferred fest und liefert für macOS, Linux und Windows getrennte Wege dorthin. Unter macOS über Homebrew mit brew install python@3.11, unter Debian-artigen Systemen mit sudo apt install python3.11 python3.11-venv, unter Windows über den Installer von Python.org mit gesetztem Add Python to PATH.

Danach folgt der übliche Ablauf:

git clone https://github.com/bRAGAI/bRAG-langchain.git cd bRAG-langchain python3.11 -m venv venv source venv/bin/activate

Bemerkenswert ist der Abschnitt Verify and Fix Python Version. Er behandelt den Fall, dass die virtuelle Umgebung auf eine andere Version zeigt, etwa Python 3.13. Die README schlägt dann vor, python --version zu prüfen und den Interpreter per symbolischem Link umzubiegen:

ln -sf $(which python3.11) $(dirname $(which python))/python

Dass dieser Schritt überhaupt dokumentiert ist, sagt etwas über die Zielumgebung. Die Notebooks hängen an Bibliotheksversionen, die unter neueren Interpretern nicht garantiert laufen. Wer die Version nicht festnagelt, debuggt später Importfehler statt RAG-Konzepte. Die README nennt außerdem API-Setups als Teil des ersten Notebooks, aber keine konkreten Variablennamen für Schlüssel. Erwartet werden Zugänge zu OpenAI für Embeddings, zu ChromaDB oder Pinecone als Vektorspeicher und zu Cohere für das Reranking im fünften Notebook.

Der Preis der Notebook-Form

Ein Notebook ist ein schlechter Ort für Code, der länger als eine Sitzung leben soll. Zellen lassen sich in beliebiger Reihenfolge ausführen, Zustand bleibt zwischen ihnen erhalten, und ein Neustart des Kernels führt regelmäßig zu Ergebnissen, die sich nicht reproduzieren lassen. Für Lehrmaterial ist das akzeptabel. Für eine Pipeline, die später in einem Dienst laufen soll, bedeutet es, dass der Code ohnehin in Module überführt werden muss.

Dazu kommt der externe Anteil. Embeddings, Reranking und Teile der Generierung laufen über fremde APIs. Jeder Durchlauf eines Notebooks kostet Geld, und die Ergebnisse hängen von Modellversionen ab, die der Anbieter ändern kann, ohne dass sich im Repository etwas bewegt. Die README adressiert dieses Problem nicht. Wer die Notebooks als Referenz für eigene Experimente nutzt, sollte den Vektorspeicher lokal halten, etwa mit ChromaDB, und nur die Embeddings extern beziehen.

Ein dritter Punkt ist die Lizenz. Die Metadaten melden NOASSERTION, es wurde also keine Standardkennung erkannt. Die README enthält dazu keine Aussage. Ob und unter welchen Bedingungen Code übernommen werden darf, lässt sich aus dem vorliegenden Material nicht beantworten und muss in der LICENSE-Datei des Repositories selbst nachgesehen werden.

Was in der Dokumentation fehlt

Die README beschreibt jedes Notebook als Liste von Stichpunkten. Sie sagt, was behandelt wird, nicht was dabei herauskommt. Es gibt keine Angabe, welche Chunk-Größe verwendet wird, kein Beispiel für eine Ausgabe, keine Aussage darüber, wie sich die Multi-Query-Variante gegenüber der einfachen Variante in der Trefferqualität schlägt, obwohl das zweite Notebook laut Beschreibung einen Comparison & Analysis-Teil enthält. Ob dort Zahlen stehen, ist aus der README nicht erkennbar.

Das ist kein Zufall, sondern eine Folge der Gattung. Ein Repository, das aus Notebooks besteht, dokumentiert seinen Inhalt über die Notebooks selbst. Die README ist Wegweiser, nicht Handbuch. Wer wissen will, wie die RRF-Gewichtung im fünften Notebook konkret aussieht, muss die Zelle öffnen. Das ist vertretbar, solange die Notebooks gepflegt sind, und riskant, sobald sie es nicht mehr sind.

Ein weiterer blinder Fleck ist die Evaluation. Retrieval-Qualität lässt sich messen, aber die README nennt kein Verfahren dafür. Wer die Notebooks als Ausgangspunkt nimmt, sollte einen eigenen kleinen Testsatz aus Fragen und erwarteten Quelldokumenten anlegen, bevor er an Chunk-Größen oder Reranking-Schwellen dreht. Sonst wird jede Änderung zur Geschmacksfrage.

Der Unterschied zu LlamaIndex

Die naheliegende Alternative ist LlamaIndex, ein Framework mit derselben Zielsetzung. Der Unterschied liegt nicht im Funktionsumfang, sondern in der Form. LlamaIndex ist eine Bibliothek mit versionierten Releases, die per pip installiert und in eigenen Code importiert wird. bRAG-langchain ist eine Sammlung von Notebooks, die man liest und kopiert.

Praktisch heißt das: Bei LlamaIndex bekommt man Abstraktionen wie Ingestion-Pipelines und Node-Parser als aufrufbare Klassen, dafür muss man sich mit deren Konventionen arrangieren. Bei bRAG-langchain sieht man die Bausteine einzeln, in der Reihenfolge, in der sie zusammenwirken, und kann jeden davon austauschen. Der Preis ist, dass man die Verdrahtung selbst schreibt und selbst aktuell hält.

Für jemanden, der zum ersten Mal eine RAG-Pipeline baut, ist der Notebook-Weg lehrreicher. Für jemanden, der in zwei Wochen eine Anwendung ausliefern muss, ist die Bibliothek der kürzere Weg. Beides gleichzeitig zu erwarten, wäre ein Missverständnis der jeweiligen Gattung.

Pflegeaufwand und was vor dem ersten Commit zu klären ist

Das Repository weist keine Releases aus. Es gibt also keine Versionsnummer, an der man sich festhalten könnte, und keinen Änderungsverlauf, aus dem hervorgeht, wann sich etwas an den Notebooks geändert hat. Der letzte Push liegt laut Metadaten im August 2026, das Repository ist nicht archiviert. Wer es forkt, übernimmt damit stillschweigend die Verantwortung für die Aktualisierung der Abhängigkeiten.

Konkret bedeutet das: Die Pins auf Python 3.11.11 und die im ersten Notebook beschriebenen API-Setups müssen bei jedem Fork gegen die aktuellen Versionen von LangChain, ChromaDB oder Pinecone geprüft werden. Die README liefert dafür kein Verfahren. Ein Upgrade von LangChain kann die Retriever-Schnittstellen verschieben, und die Notebooks werden nicht mitwandern.

Die Lizenzfrage bleibt offen. NOASSERTION ist eine Meldung über fehlende Erkennung, keine Aussage über Rechte. Vor einer Übernahme von Code in ein eigenes Produkt gehört die LICENSE-Datei gelesen, nicht die README. Wer das Repository nur zum Lernen in einer lokalen Umgebung nutzt, hat mit dieser Frage nichts zu tun.

Redaktionelles Fazit

Sinnvoll ist das Repository für Entwickler, die RAG-Konzepte an lauffähigen Notebooks nachvollziehen wollen, bevor sie eine eigene Pipeline schreiben, und die bereit sind, Python 3.11.11 in einer virtuellen Umgebung bereitzustellen. Wer eine betreute Bibliothek mit SemVer, Changelog und Issue-Tracking sucht, ist hier falsch, weil das Repository keine Releases ausweist und die Lizenz als NOASSERTION gemeldet ist. Vor jedem produktiven Einsatz ist die Lizenzdatei im Repository selbst zu prüfen und die API-Kosten für OpenAI, Pinecone und Cohere sind gegen ein lokales Setup mit ChromaDB abzuwägen.

Offizielle Quellen

1. bragai/bRAG-langchain on GitHub
2. Issues
3. Project website
4. README