Lokaler RAG-Assistent für Onboarding-Dokumentation

Die Onboarding-Dokumentation lag als Markdown-Dateien vor. Diese Form beantwortet eine Frage nur dann, wenn der Fragende bereits weiss, in welchem Dokument und in welchem Abschnitt die Antwort steht. Der Suchaufwand liegt damit beim Neuen, nicht bei der Dokumentation — und genau an dieser Stelle entsteht bei Onboarding der groesste Zeitverlust.

Aus dieser Ausgangslage ergaben sich zwei Klassen von Anforderungen. Funktional gefordert war, dass ein Fragebereich semantisch — also ohne Kenntnis der exakten Formulierung — auf die passenden Abschnitte fuehrt, dass die Antwort aus diesen Abschnitten erzeugt wird, und dass zu jeder Antwort die verwendete Quelle mitgeliefert wird. Damit das Ganze pruefbar und nachvollziehbar bleibt, muss die Herkunft einer Aussage eindeutig sein.

Nichtfunktional war die Betriebsbedingung: Die Verarbeitung musste lokal erfolgen. Das ist hier keine Vorliebe, sondern eine Anforderung aus dem Einsatzkontext — eine Onboarding-Dokumentation, die an externe Dienste geht, waere im Betrieb eine Abhaengigkeit und ein Risiko, und die Ausfuehrung auf schwacher Hardware (Zielgeraet Raspberry Pi 4) waere ueber Netzdienste nicht sinnvoll abbildbar. Die Konsequenz fuer die Architektur war eindeutig: kein externes Embedding-Modell, keine gehostete Vektordatenbank, kein Cloud-Inferenz.

Die zentrale Entscheidung war der Einsatz von Retrieval-Augmented Generation statt eines Sprachmodells mit eingebautem Kontext. Der Unterschied ist nicht theoretisch: Ein Modell, das die Onboarding-Dokumentation aus seinem Gewicht beantwortet, kennt den Stand der Dokumentation nicht und kann eine veraltete Anweisung genauso fluessig formulieren wie eine aktuelle. Beim RAG-Ansatz ist die Quelle der Wahrheit der zur Laufzeit gelesene Abschnitt — die Antwort kann auf einen konkreten Textabschnitt zurueckgefuehrt werden, und das Modell formuliert nur.

Diese Entscheidung verteilt die Aufgabe auf drei Bausteine, die jeweils eine eigene, klar abgegrenzte Verantwortung haben. Embeddings uebersetzen Abschnitte in Vektoren, die semantische Aehnlichkeit abbilden. Der Vektorindex beantwortet die Frage, welche Abschnitte zum Fragetext passen. Das Sprachmodell erzeugt aus Frage und den gefundenen Abschnitten die Antwort. Der letzte Schritt ist bewusst der einzige, der sprachliche Qualitaet liefert — die inhaltliche Richtigkeit entscheidet sich davor.

Diese Trennung ist auch der Grund fuer die Trennung von Retrieval und Generierung in der Implementierung: Der Retrieval-Teil ist deterministisch und nachvollziehbar — gleiche Frage, gleicher Index, gleiche Treffer. Erst danach entsteht generierter Text, und genau dort liegt die Fehlermoeglichkeit. Diese Grenze erlaubt es, Retrieval-Qualitaet und Antwortqualitaet getrennt zu beurteilen.

Markdown ist strukturiert, aber nicht segmentiert: Eine Datei enthaelt Ueberschriften, Absaetze, Listen und Codebloecke in einer linearen Reihenfolge. Fuer die Vektorsuche muss daraus eine Menge getrennt abfragbarer Einheiten entstehen. Die Dateien werden deshalb gelesen und in Abschnitte zerlegt, die thematisch zusammenhaengen.

Der entscheidende Punkt bei diesem Schritt ist die Grenzziehung. Wird zu gross geschnitten, verliert ein Abschnitt den Zusammenhang und die Einbettung bildet ein Gemisch ab. Wird zu klein geschnitten, verliert ein Abschnitt die Aussage, die eigentlich gesucht wird. Deshalb wird beim Zerlegen nicht an Zeilenumbruechen geschnitten, sondern an den Absatz- und Ueberschriftengrenzen der Markdown-Struktur.

Jeder Abschnitt behaelt eine Referenz auf seinen Ursprung: Dateiname und Position. Diese Referenz ist die Grundlage der Quellenangabe in der spaeteren Antwort. Sie wird beim Einlesen mitgefuehrt, nicht spaeter rekonstruiert — das ist der Unterschied zwischen einer belastbaren und einer unpruefbaren Quellenangabe.

Dokumentiert ist dieser Aufbereitungsschritt ueber die Bestandsgroesse und ueber die Chunking-Parameter: Aus 47 Markdown-Dateien der Onboarding-Dokumentation wurden 81 Chunks erzeugt. Als angestrebte Chunkgroesse sind 200 Woerter hinterlegt; die dokumentierten Grenzen liegen bei minimal 80 und maximal 300 Woertern. Ueberschneidung wird mit zwei Saetzen realisiert, und zwar dort, wo eine erzwungene Trennung an einer Abschnittsgrenze sonst einen Absatz ohne Kontext erzeugen wuerde.

Die Abschnitte werden mit Sentence Transformers eingebettet. Als Modell dient all-MiniLM-L6-v2: ein kompaktes, vortrainiertes Sentence-Transformer-Modell, das einen Abschnitt in einen 384-dimensionalen Vektor uebersetzt. Klein und ohne GPU lauffaehig, ist es der Kompromiss, der auf Ziel-Hardware sinnvoll betreibbar bleibt.

Zur Einordnung des Modells ist eine Korrektur wichtig, weil sie in der Projektbeschreibung leicht falsch laeuft: all-MiniLM-L6-v2 ist primaer englischsprachig ausgerichtet und wurde nicht speziell fuer die deutsche Sprache trainiert. Im Projekt wurde die Anwendung sowohl mit deutschsprachigen als auch mit englischsprachigen Anfragen erprobt — eine praktische Beobachtung, aber kein Beleg fuer ein deutschsprachiges Training oder fuer vollwertige Mehrsprachigkeit.

Die Vektorsuche selbst laeuft ueber FAISS mit dem Index-Typ IndexFlatL2. IndexFlatL2 bedeutet exakte Suche: Der Index fuehrt keinen Approximations- oder Clustering-Schritt aus, sondern berechnet die Distanz zu allen gespeicherten Vektoren. Bei einer Onboarding-Dokumentation mit typischerweise einigen hundert Abschnitten ist der lineare Scan unkritisch, und dafuer liefert die exakte Suche zwei Eigenschaften, die bei einer naeherungsweisen Suche nicht garantiert waeren: deterministische Treffer und das Fehlen von Approximationsfehlern.

Die Distanzmessung ist die euklidische L2-Distanz. Entscheidend fuer die Interpretation ist, was daraus folgt: all-MiniLM-L6-v2 liefert normalisierte Embeddings, bei denen die Vektoren bereits auf die Einheitskugel projiziert sind. Bei normalisierten Vektoren ist die L2-Distanz zur Cosinus-Ahnlichkeit proportional — die Trefferreihenfolge entspricht der semantischen Aehnlichkeit. Genau diese Umrechnung macht aus einer Distanz eine verstaendliche Groesse: kleiner ist naeher.

Fuer jede Frage wird derselbe Einbettungsweg genommen wie fuer die Dokumente. Das ist zwingend: eine Frage kann nur dann mit einem Abschnitt verglichen werden, wenn beide im selben Raum liegen. Verwendet man fuer die Frage ein anderes Modell, ist der Vergleich bedeutungslos. Die Frage wird eingebettet, gegen den Index abgefragt, und die naechstgelegenen Abschnitte werden zurueckgegeben — top_k = 4.

Die Generierung uebernimmt Llama 3.2 3B Instruct. Das Modell wird in der Quantisierung Q4_K_M gehalten — ein 4-Bit-Format, das den Speicherbedarf der Modellgewichte deutlich reduziert und damit eine ressourcenschonendere lokale Ausfuehrung ueberhaupt erst moeglich macht. Gegenueber hoeherpraezisen Modellgewichten koennen dabei Qualitaetsverluste auftreten; eine konkrete Veraenderung der Perplexitaet ist im Projekt nicht gemessen worden und wird hier deshalb auch nicht beziffert.

Die Anbindung erfolgt ueber llama-cpp-python, das die Inferenz direkt gegen die Llama.cpp-Laufzeit fuehrt. Das ist kein Framework-Overhead, sondern der eigentliche Grund fuer die Wahl: llama-cpp-python laesst das GGUF-Format und die Quantisierung direkt nutzen, ohne dass das Modell fuer den Betrieb zuerst in ein anderes Format konvertiert werden muss.

Der Prompt wird aus der Frage und den zurueckgegebenen Abschnitten zusammengesetzt. Die Anweisung an das Modell bindet die Antwort an das bereitgestellte Material: Die Abschnitte sind der Kontext, und die Antwort soll ausschliesslich daraus abgeleitet sein. Zusammen mit einem Distanzschwellenwert, dem System-Prompt und den Quellenmetadaten richtet dieses Vorgehen die Antworten auf die bereitgestellten Informationen aus.

Diese Ausrichtung ist eine Massnahme, keine Garantie: Sie schraenkt den verfuegbaren Kontext ein und weist das Modell an, daraus zu formulieren, sie schliesst aber nicht aus, dass das Sprachmodell gelegentlich unbelegte Aussagen erzeugt. Die Quellenmetadaten machen genau das pruefbar, indem die erzeugten Inhalte nachtraeglich gegen die angegebenen Abschnitte nachvollzogen werden koennen.

Der lokale Betrieb hat eine Konsequenz fuer die Antwortzeit, die spaeter quantitativ sichtbar wird: Die Generierung eines Textes ist hier kein API-Aufruf, sondern eine Berechnung auf der vorhandenen CPU. Antwortlaenge und Tokenrate des Modells gehen damit direkt in die Wartezeit ein. Das ist der Grund, weshalb die Antwortzeit des Systems im Bereich von 12 bis 45 Sekunden liegt.

Die Umsetzung ist in Python realisiert und gliedert sich in eine vorgelagerte Offline-Phase und die laufende Anfrageverarbeitung. In der vorgelagerten Phase wird die Markdown-Dokumentation gelesen, in Chunks unterteilt, mit Sentence Transformers eingebettet und in FAISS indexiert. Waehrend einer Benutzeranfrage wird ausschliesslich der vorhandene FAISS-Index durchsucht: Die Frage wird eingebettet, der Index abgefragt, die relevanten Textabschnitte werden ermittelt und als Kontext fuer die lokale LLM-Inferenz verwendet. Der Dokumentenbestand wird bei einer Frage nicht erneut verarbeitet.

Die Trennung der Phasen ist eine bewusste Entscheidung: Der Index wird einmal gebaut und dann wiederverwendet. Das haelt den Antwortpfad frei von Dokumentenverarbeitung und macht die Latenz der einzelnen Frage vorhersagbar — der Preis ist, dass eine Aenderung an der Dokumentation einen Neuaufbau des Index erfordert.

Die Oberflaeche ist mit Streamlit umgesetzt. Das ist bewusst kein Framework fuer Produktbetrieb, sondern ein Werkzeug fuer den Einsatz, in dem die Anwendung laufen soll: eine lokale, im Browser bedienbare Oberflaeche ohne eigene Frontend-Entwicklung, die auf demselben System laeuft wie der Rest der Pipeline. Die Ausgabe umfasst die generierte Antwort und die Angabe der verwendeten Quellen.

Die Abnahme erfolgte ueber Musskriterien. Die funktionalen Musskriterien MK1 bis MK7 wurden erfuellt, die beiden Leistungsziele MK8 und MK9 wurden nicht erfuellt. Ueber die Kriterien hinaus wurde die Antwortzeit gemessen, und dabei hat sich ein Abstand zwischen Ziel und Ist ergeben, der im Projekt bewusst nicht geglaettet wurde.

Die Pruefung umfasste die Abfrage der semantischen Suche, die Anzeige der Quellen zu einer Antwort, die vollstaendig lokale Ausfuehrung ohne externen Dienst sowie die Erzeugung der Antwort selbst. Diese vier Pruefschritte bilden den funktionalen Kern des Systems ab — sie entscheiden, ob die Architekturentscheidung aus Abschnitt B tatsaechlich traegt.

Die Antwortqualitaet wurde im Hauptbericht mit 7/10 bewertet, und zwar anhand von 20 Testfragen. Das Abnahmeprotokoll weist 7,3/10 aus. Beide Werte sind dokumentiert; sie beziehen sich auf unterschiedliche Erhebungen und werden hier nicht zu einem gemeinsamen Wert zusammengefuehrt. Es handelt sich um eine Gesamtbewertung der Antwortguete — nicht um eine Zaehlung, wie viele der 20 Fragen korrekt beantwortet wurden.

Die Leistungsmessung war der Punkt, an dem das Projekt sein eigenes Ziel verfehlt hat. Der Hauptbericht nennt Antwortzeiten von 12 bis 45 Sekunden, die Abnahmetabelle 15 bis 45 Sekunden; im Testfall TF-F10 ergaben sich bei zehn Testfragen durchschnittlich rund 30 Sekunden. Das angestrebte Ziel von unter zehn Sekunden (MK8) wurde in allen Erhebungen verfehlt.

Ergänzend hat das Abnahmeprotokoll fuenf Negativtests dokumentiert, die korrekt abgelehnt wurden, sowie den Umstand, dass zwei Mitarbeiter die Anwendung ohne vorherige Einweisung bedienen konnten.

Die funktionalen Musskriterien MK1 bis MK7 sind erfuellt. Das System durchsucht die Onboarding-Dokumentation semantisch, erzeugt Antworten mit Quellenangabe und laeuft vollstaendig lokal. Der Kern des Anspruchs ist damit eingeloest.

Zwei Ziele wurden nicht erreicht. Das Leistungsziel von unter zehn Sekunden (MK8) wurde verfehlt: Der Hauptbericht nennt Antwortzeiten von 12 bis 45 Sekunden, die Abnahmetabelle 15 bis 45 Sekunden, der Testfall TF-F10 liegt bei durchschnittlich rund 30 Sekunden. Das angestrebte Zielgeraet Raspberry Pi 4 (MK9) wurde nicht erreicht.

Das Raspberry-Pi-Ziel wurde im Rahmen des Projekts nicht erfolgreich installiert und betrieben — dieses Ziel ist damit nicht erfuellt. Die Dokumentation nennt dafuer mehrere Faktoren: die RAM-Beschraenkung des Geraets, die CPU-Leistung und Schwierigkeiten bei der Konfiguration der Laufzeitumgebung. Eine einzelne Ursache laesst sich nicht als zweifelsfrei nachgewiesen angeben, und es waere auch nicht belegbar, dass ausschliesslich der Speicherbedarf des 3B-Modells ausschlaggebend war.

Auch der Ressourcenverbrauch ist im Test belegt: Durchschnittlich wurden rund 2,4 GB Arbeitsspeicher und rund 65 % CPU-Auslastung gemessen. Diese Werte beziehen sich auf den dokumentierten Testkontext und sind weder eine allgemeine Hardwareanforderung noch garantierte Verbrauchswerte.

Der ehrliche Befund ist damit zweigeteilt: Die Architektur traegt funktional, und sie kostet Leistung. Genau diese Abwaegung — lokale, nachvollziehbare, an den Kontext gebundene Antworten gegenueber Antwortzeit und Ziel-Hardware — ist die zentrale Erkenntnis des Projekts.

Als bewaehrt hat sich die Trennung der Verantwortlichkeiten. Retrieval und Generierung sind getrennt pruefbar, die Antworten sind an den bereitgestellten Kontext gebunden, und der lokale Betrieb hat die Datenschutzfrage gar nicht erst aufgemacht. Die exakte Suche in einem kleinen Index hat sich als die richtige Wahl erwiesen — deterministisch, ohne Approximationsfehler, ohne den Aufwand einer Indexpflege.

Ebenso wichtig ist, was diese Bindung nicht leistet. Der Retriever begrenzt den verfuegbaren Kontext auf relevante Dokumentationsabschnitte, der System-Prompt weist das Sprachmodell an, Antworten auf Grundlage dieses Kontexts zu formulieren, und die Quellenmetadaten ermoeglichen eine nachtraegliche Ueberpruefung der erzeugten Inhalte. Das richtet die Antworten aus — es garantiert aber nicht, dass das Sprachmodell niemals unbelegte Aussagen generiert. Die durchgefuehrten Negativtests zeigen, dass fuenf von fuenf Negativfaellen im Abnahmeprotokoll korrekt abgelehnt wurden.

Sichtbar geworden ist, dass die Antwortzeit in dieser Architektur keine Eigenschaft des Modells ist, sondern eine Eigenschaft der Kette aus Retrieval, Promptaufbau und CPU-Generierung. Das ist die praktische Lehre fuer den Einsatz: Ein System kann funktional vollstaendig sein und trotzdem in der Interaktionsqualitaet (Antwortzeit) verfehlen — und die Ursache liegt dann in der Betriebsentscheidung, nicht im Code.

Technisch moeglich, aber nicht umgesetzt: eine Erhoehung von top_k, um mehr Kontext in die Generierung zu geben; ein groesserer Arbeitsspeicher, um die Ziel-Hardware doch noch zu erreichen; ein Neuaufbau des Index ohne den Zykus ueber die Indexdatei zu unterbrechen; und ein Embedding-Cache fuer haeufig wiederkehrende oder bereits bekannte Fragen. Zur letzten Optimierung ist die Einordnung wichtig: Sie entlastet nur bekannte Fragen — neue, bislang unbekannte Fragen muessen weiterhin eingebettet werden. Ein pauschaler Wegfall des Einbettungsschritts ist mit dem dokumentierten Stand nicht vereinbar.