Controllable-RAG-Agent: ein deterministischer Graph als Steuerungsschicht über Vektor-Retrieval

Welche Fragearten einfaches Vektor-RAG nicht beantwortet

Die README beschreibt den Ausgangspunkt klar: Das Projekt richtet sich an komplexe Fragen, die eine reine Ähnlichkeitssuche nicht lösen kann. Das ist ein bekanntes Muster. Wer einen Satz wie "Wie hängen die Argumente aus Kapitel drei mit der Schlussfolgerung in Kapitel neun zusammen?" an einen Vektor-Index stellt, bekommt Chunks, die lexikalisch oder semantisch nahe an der Formulierung liegen. Die eigentliche Arbeit, das Verbinden zweier weit auseinanderliegender Textstellen, findet nicht statt. Der Agent adressiert genau diese Lücke, indem er eine Frage in Teilschritte zerlegt und diese nacheinander abarbeitet. Zielgruppe sind laut Repository Entwickler, die mit LangChain und LangGraph vertraut sind und ein eigenes Textkorpus aus PDFs erschließen wollen. Der Aufbau ist ausdrücklich als Demonstration angelegt, nicht als fertiges Produkt.

Der Ablauf von der PDF bis zur Antwort

Die README listet die Verarbeitungskette in nummerierten Schritten. Zuerst werden PDFs geladen und in Kapitel zerlegt. Danach folgt eine Textvorverarbeitung, die auf bessere Zusammenfassungen und Kodierung zielt. Für jedes Kapitel erzeugt ein Sprachmodell eine ausführliche Zusammenfassung. Zusätzlich entsteht eine Datenbank für Fragen, die wörtliche Zitate aus dem Buch benötigen. Schließlich werden Buchinhalt und Kapitel-Zusammenfassungen in Vektorspeicher kodiert. Diese Trennung zwischen Zusammenfassungsebene und Volltextebene ist der interessanteste Teil des Entwurfs: Der Agent kann zuerst grob über Zusammenfassungen navigieren und erst dann in den Volltext absteigen, wenn ein Zitat gebraucht wird. Die README bezeichnet den deterministischen Graphen als das Gehirn des Agenten und nennt als Kernmerkmale mehrstufiges Schlussfolgern, adaptive Planung und Halluzinationsvermeidung dadurch, dass Antworten ausschließlich auf den bereitgestellten Daten beruhen sollen. Ob diese Zusicherung im Einzelfall hält, hängt an der Qualität der Zusammenfassungen und an der Frage, wie der Graph mit fehlenden Belegen umgeht.

Deterministisch heißt hier nicht ohne Sprachmodell

Der Begriff deterministisch bezieht sich auf die Reihenfolge der Schritte, nicht auf die Ausgaben. Der Graph gibt vor, welche Knoten in welcher Abfolge durchlaufen werden, während die Inhalte an den Knoten von Sprachmodellen erzeugt werden. Das ist eine bewusste Einschränkung gegenüber freien Agenten, die selbst entscheiden, welches Werkzeug sie als Nächstes aufrufen. Der Vorteil liegt in der Nachvollziehbarkeit: Der Pfad durch die Verarbeitung ist im Graphen festgelegt und damit prüfbar. Der Nachteil ist genauso real. Fragen, die nicht in das vorgesehene Muster passen, werden nicht durch eine andere Strategie aufgefangen, sondern laufen durch dieselbe Kette. Adaptive Planung bedeutet in diesem Rahmen, dass der Plan an einer definierten Stelle im Graphen aktualisiert wird, nicht dass der Agent die Struktur des Graphen selbst umbaut. Wer einen vollständig offenen Agenten erwartet, wird hier etwas anderes finden.

Inbetriebnahme: Notebook, Umgebung, Modellzugang

Das Repository ist primär in Jupyter Notebook geschrieben. Es gibt keine abrufbaren Releases, und die README nennt weder eine versionsgebundene Installationsanweisung noch eine requirements-Datei mit exakten Pins. Der Einstieg läuft daher über das Notebook selbst. Für den Modellzugang ist ein OpenAI-Schlüssel erforderlich, wie die Themenliste des Repositories mit dem Eintrag openai nahelegt; die README zeigt dazu kein vollständiges Konfigurationsbeispiel. Die Qualitätsbewertung erfolgt laut README über Ragas-Metriken, was bedeutet, dass für eine belastbare Auswertung ein eigener Frage-Antwort-Datensatz vorhanden sein muss. Wer das Projekt ernsthaft nutzen will, sollte zuerst die im Notebook gesetzten Modellnamen und Umgebungsvariablen prüfen und diese gegen die eigene Kosten- und Datenschutzlage abgleichen. Ohne diesen Schritt bleibt unklar, welche Aufrufe tatsächlich nach außen gehen.

Wo der Aufbau an seine Grenzen stößt

Die stärkste Einschränkung steckt in der Vorverarbeitung. Der Ansatz setzt PDFs mit erkennbarer Kapitelstruktur voraus. Technische Handbücher, Ticketverläufe, Chatprotokolle oder ein Verzeichnis lose gesammelter Markdown-Dateien lassen sich nicht ohne Weiteres in Kapitel schneiden, und genau dieser Schnitt trägt die Zusammenfassungsebene. Fällt er weg, verliert der Agent seinen Navigationsvorteil. Dazu kommt der Kostenfaktor: Für jedes Kapitel entsteht eine Zusammenfassung, und jede Anfrage durchläuft mehrere Modellaufrufe. Bei einem umfangreichen Korpus ist die Indexierung damit ein eigener Rechenposten, der bei einer einfachen Vektorsuche entfällt. Ein weiterer Punkt ist die Halluzinationsvermeidung. Die README formuliert sie als Eigenschaft des Systems. Erreichbar ist sie nur, wenn der Graph Fragen ohne ausreichende Belege erkennbar ablehnt. Ob und wie er das tut, lässt sich aus dem vorliegenden Material nicht bestätigen und muss am Code geprüft werden.

Was der Vergleich mit einem schlichten Vektor-Index zeigt

Die naheliegende Alternative ist ein einzelner Vektorspeicher mit Chunking und einer Top-k-Suche, wie er in unzähligen RAG-Beispielen verwendet wird. Der Unterschied liegt nicht in der Bibliothek, sondern im Datenfluss. Beim einfachen Ansatz gibt es genau einen Retrieval-Schritt, dessen Ergebnis direkt in den Prompt fließt. Beim Controllable-RAG-Agent existieren zwei Ebenen: Zusammenfassungen für die Orientierung, Volltext für Belege, dazu eine getrennte Ablage für Zitatfragen. Diese zweite Ebene kostet Indexierungszeit und Speicher, erkauft dafür aber eine Zwischenstufe, auf der ein Sprachmodell entscheiden kann, welcher Teil des Korpus überhaupt relevant ist. Für kurze Dokumente oder Faktenfragen mit eindeutiger Fundstelle ist der einfache Index die bessere Wahl. Der Agent spielt seine Stärke erst aus, wenn eine Frage mehrere Textstellen verbinden muss und die Begründung nachvollziehbar bleiben soll.

Lizenz, Wartung und der Preis des Mitziehens

Das Projekt steht unter Apache-2.0. Diese Lizenz erlaubt kommerzielle Nutzung und Änderungen, verlangt aber, dass Lizenz- und Urheberrechtshinweise erhalten bleiben und geänderte Dateien als geändert gekennzeichnet werden. Wer den Code in ein eigenes Produkt überführt, sollte diesen Punkt vor der Verteilung klären; eine rechtliche Bewertung kann dieser Text nicht leisten. Zur Wartung ist die Faktenlage dünn. Es gibt keine abrufbaren Releases, der letzte Push liegt laut Repository-Angabe bei September 2026, und die README verweist stark auf Buch, Kurs und Newsletter des Autors. Der eigentliche Inhalt liegt in Notebook-Zellen, nicht in einer versionierten Bibliothek mit SemVer. Wer den Ansatz übernimmt, übernimmt damit auch die Verantwortung für Abhängigkeiten wie LangChain und LangGraph, deren APIs sich zwischen Versionen ändern können. Ein Upgrade-Pfad ist im Repository nicht dokumentiert. Das ist bei einem Lehrbeispiel üblich, für einen Produktivbetrieb aber ein Posten, der eingeplant werden muss.

Redaktionelles Fazit

Sinnvoll ist das Repository für Teams, die einen nachvollziehbaren, mehrstufigen Frage-Antwort-Ablauf über eigenen PDF-Beständen prototypen wollen und dafür Python- und LangGraph-Kenntnisse mitbringen. Wer einen sofort deploybaren Dienst mit stabiler API sucht oder dessen Daten nicht als PDF mit Kapitelstruktur vorliegen, sollte zuerst prüfen, ob der Aufwand für die Anpassung des Graphen und der Notebook-Zellen im Verhältnis zum Nutzen steht. Vor jedem Einsatz zu verifizieren sind die tatsächlich im Code hinterlegten Modellnamen, die Qualität der Kapitel-Zusammenfassungen auf dem eigenen Korpus und das Verhalten des Graphen bei Fragen, die sich nicht in Teilaufgaben zerlegen lassen.

Offizielle Quellen

1. Issues
2. License: Apache-2.0
3. NirDiamant/Controllable-RAG-Agent on GitHub
4. README