RAG |

CogniVault Backend erklärt, Teil 1 · Das Backend kennenlernen: Drei Prozesse, vier Schichten

Fri, 12 Jun 2026 00:00:00 +0000

Alle Abkürzungen werden im Anhang am Ende der Seite vollständig erklärt.

Wenn Leute das erste Mal das CogniVault-Repository öffnen, höre ich meistens eine Variante der Frage: “Wo fange ich überhaupt an?” Da gibt es einen RAG-Agenten, einen FAISS-Index, einen DBOS-Workflow, einen Ollama-Host — und wenn du gerade erst in die Tech-Welt einsteigst, ist jedes dieser Wörter wie eine verschlossene Tür.

Diese Serie öffnet die Türen, eine nach der anderen. Kein RAG-Vorwissen vorausgesetzt, jede Abkürzung wird ausgeschrieben und jede Behauptung lässt sich im nachprüfen. Falls du meine schon gelesen hast, betrachte diese Serie als die Führung, die eigentlich hätte zuerst kommen sollen.

Lass uns das mal aufzeichnen.

Die ganze App besteht aus drei Prozessen

Mit CogniVault kannst du mit deinen eigenen Dokumenten chatten und sie in Quizzes, Workshops, Karteikarten und Mindmaps verwandeln — und dabei verlässt absolut nichts jemals deinen Rechner. (Das Warum hinter dieser Einschränkung ist eine eigene Geschichte: .)

Man könnte erwarten, dass so eine App ein Wildwuchs an Microservices ist. Aber es sind genau drei Prozesse:

Prozess	Was er macht
Das Python-Backend	Eine FastAPI-App auf Port 8000 — sie serviert auch das kompilierte React-Frontend als statische Dateien
Ollama	Der lokale Model-Server auf Port 11434, auf dem die KI-Modelle laufen
PostgreSQL	Ein Docker-Container, der nur für Workflow-Checkpoints genutzt wird — niemals für deine Dokumente

Alles andere — deine Dateien, der Suchindex, dein Chatverlauf, deine Quiz-Ergebnisse — ist einfach eine Datei auf der Festplatte. Das ist keine Faulheit; das ist das Privatsphäre-Argument physisch umgesetzt. Du kannst jedes Byte, das die App speichert, mit einem Texteditor und einem SQLite-Browser öffnen.

Die vier Schichten

Bevor wir Technologien beim Namen nennen, hier das mentale Modell, das du für die ganze Serie im Kopf behalten solltest. Das Backend besteht von oben nach unten aus vier Schichten:

Schicht 1 — die Web-Schicht. Eine FastAPI-Anwendung nimmt jeden HTTP-Request entgegen und routet ihn an einen von sechs Routern: Chat (/rag), Wissensmanagement (/upload, /ingest), Lerntools (/api/study/*), Fortschritt (/api/progress/*), Sprache (/api/transcribe) und Chatverlauf (/api/history). FastAPI (ein modernes Python-Web-Framework) generiert unter /api/docs zudem automatisch eine interaktive API-Dokumentation, was der beste Weg ist, um das Backend zu erkunden, ohne eine Zeile Code lesen zu müssen.

Schicht 2 — die Intelligenz-Schicht. Zwei KI-Modelle mit zwei verschiedenen Jobs. gemma4:e4b generiert: Chat-Antworten, Gedankengänge (Reasoning), Bildanalyse und Tool-Aufrufe. embeddinggemma erstellt Embeddings: Es verwandelt Text in Vektoren (Zahlenlisten, die Bedeutung einfangen), sodass ähnliche Ideen mathematisch gefunden werden können. Beide laufen innerhalb von Ollama — stell dir Ollama wie Docker vor, aber für KI-Modelle.

Schicht 3 — die Retrieval-Schicht. Eine Suchmaschine über deine Dokumente, die semantische Suche (finde Dinge mit gleicher Bedeutung) mit Keyword-Suche (finde exakte Zeichenketten) kombiniert. Teil 3 dieser Serie dreht sich komplett um diese Schicht.

Schicht 4 — die Persistenz-Schicht. Vier Speichersysteme, jedes für einen speziellen Job ausgewählt: ein FAISS-Index plus einer JSON-Datei für durchsuchbares Wissen, SQLite für Lerndaten, PostgreSQL für Workflow-Checkpoints und einfache JSON-Dateien für den Chatverlauf.

Ein Diagramm, alle wichtigen Teile

flowchart TB subgraph CLIENT["Browser"] UI["React Frontend
(kompiliert, serviert von FastAPI)"] end subgraph SERVER["FastAPI Backend — Port 8000"] ROUTERS["6 Router
rag · knowledge · study ·
progress · audio · history"] AGENT["RAG Agent
(Strands SDK, 6 Tools)"] VDB["VectorDB
FAISS + BM25 + RRF"] INGEST["Ingestion
(DBOS dauerhafter Workflow)"] GEN["Study Generatoren
quiz · workshop · cards · mindmap"] PROG["Fortschrittstracker
+ 25 Achievements"] end subgraph OLLAMA["Ollama — Port 11434"] GEMMA["gemma4:e4b
chat · thinking · vision · tools"] EMBED["embeddinggemma
Text zu Vektoren"] end subgraph STORAGE["Lokaler Speicher"] FAISSF["vector_store.faiss + .json"] SQLITE["progress.db (SQLite)"] PG["PostgreSQL
nur Workflow-Status"] DOCS["docs/ Ordner + chat_history.json"] end UI --> ROUTERS ROUTERS --> AGENT --> VDB AGENT --> GEMMA VDB --> EMBED ROUTERS --> INGEST --> EMBED INGEST --> PG INGEST --> FAISSF VDB --- FAISSF ROUTERS --> GEN --> GEMMA GEN --> SQLITE ROUTERS --> PROG --> SQLITE ROUTERS --> DOCS

Behalte dieses Bild im Hinterkopf — die Teile 2, 3 und 4 zoomen jeweils in einen Bereich davon hinein.

Der Tech-Stack und warum jedes Teil seinen Platz verdient hat

Die komplette Liste der Abhängigkeiten (Dependencies) lebt in der requirements.txt. Hier ist das, was wichtig ist, gruppiert nach Aufgabe:

Requests bearbeiten. FastAPI definiert die Endpoints und validiert jeden Request und jede Response mit Pydantic (einer Datenvalidierungs-Bibliothek — stell es dir wie einen strengen Zollbeamten für JSON vor). Uvicorn ist der ASGI-Server (Asynchronous Server Gateway Interface — der Python-Standard, der es einem Prozess erlaubt, viele gleichzeitige Requests zu jonglieren), der das Ganze am Ende ausführt.

Denken. Ollama hostet gemma4:e4b — das e4b-Tag steht für die Variante mit rund vier Milliarden effektiven Parametern, was ungefähr einem 9,6 GB Download entspricht — und embeddinggemma (ca. 622 MB). Das Agentenverhalten wird mit dem Strands Agents SDK gebaut, welches das Modell in einen Loop (Schleife) verpackt, in dem es Tools aufrufen, die Ergebnisse lesen und erst danach antworten kann. (Wo ich Ollama in Relation zu Docker laufen lasse, ist eine bewusste Entscheidung mit eigener Hintergrundgeschichte: .)

Dinge finden. FAISS (Facebook AI Similarity Search — Metas Vektorsuch-Bibliothek) kümmert sich um semantische Lookups; rank-bm25 kümmert sich um Keyword-Lookups; eine Formel namens Reciprocal Rank Fusion vereint die beiden. Teil 3 packt all das genauer aus.

Dokumente lesen. pypdf für PDFs, mit einem OCR-Fallback (Optical Character Recognition — verwandelt Bilder von Text in echten Text) für gescannte Seiten via pymupdf und Tesseract. Word, PowerPoint und Excel bekommen jeweils ihren eigenen Extractor. trafilatura zieht sauberen Artikeltext aus Webseiten.

Keine Arbeit verlieren. DBOS macht die Ingestion-Pipeline dauerhaft (durable) — jeder Schritt bekommt einen Checkpoint in PostgreSQL, sodass bei einem Absturz fortgesetzt statt von vorn begonnen wird. Teil 2 zeigt das in Aktion.

Sich erinnern. SQLite — eine vollwertige Datenbank-Engine, die in einer einzigen Datei namens progress.db lebt — hält deine Lernsitzungen, Errungenschaften (Achievements), Quizzes, Workshops, Karteikartendecks und Mindmaps fest.

Anhang: Abkürzungen in diesem Post

Das Versprechen dieser Serie ist “keine unerklärten Abkürzungen”, also ist hier die Tabelle, von der ich wünschte, sie wäre in jedem technischen Tutorial dabei.

Abkürzung	Volle Form	Bedeutung in einfachem Deutsch
LLM	Large Language Model	Ein neuronales Netz, das mit massenhaft Text trainiert wurde und Sprache lesen und generieren kann
RAG	Retrieval-Augmented Generation	Hole erst relevante Passagen aus deinen Dokumenten und lass das Modell daraus antworten — statt aus seinem Trainingsgedächtnis
API	Application Programming Interface	Die Menge an URLs, die das Frontend aufruft, um mit dem Backend zu sprechen
ASGI	Asynchronous Server Gateway Interface	Der Python-Standard, der es dem Server erlaubt, viele Anfragen gleichzeitig zu bearbeiten
JSON	JavaScript Object Notation	Das universelle Textformat für strukturierte Daten
NDJSON	Newline-Delimited JSON	Ein Stream, bei dem jede Zeile ein eigenes JSON-Objekt ist — ideal, um KI-Antworten Stück für Stück (Chunk für Chunk) zu streamen
FAISS	Facebook AI Similarity Search	Metas Bibliothek, um Vektoren zu speichern und die ähnlichsten schnell zu finden
BM25	Best Match 25	Eine klassische Keyword-Ranking-Formel — die 25. Ranking-Funktion, die im Okapi Information-Retrieval-System entwickelt wurde
RRF	Reciprocal Rank Fusion	Eine Formel zum Zusammenführen mehrerer gerankter Ergebnislisten, die nur die Ränge benutzt
ANN	Approximate Nearest Neighbour	Eine Geschwindigkeits-Abkürzung, die viele Vektordatenbanken nehmen. CogniVault nutzt stattdessen bewusst einen exakten Index — präzise und für eine persönliche Bibliothek völlig schnell genug
DBOS	Database-Oriented Operating System (das Forschungsprojekt, aus dem es entstand)	Eine Bibliothek, die Workflow-Schritte in einer Datenbank zwischenspeichert, sodass abgestürzte Jobs fortgesetzt werden können
SQL / SQLite	Structured Query Language / SQLite	Die Sprache von relationalen Datenbanken / eine winzige Datenbank, die in einer Datei lebt
OCR	Optical Character Recognition	Verwandelt Bilder von Text (Scans) in maschinenlesbaren Text
SHA-256	Secure Hash Algorithm, 256-bit	Eine Fingerabdruck-Funktion — jede Datei wird auf einen eindeutigen Hash abgebildet, genutzt um geänderte Dateien zu erkennen
CORS	Cross-Origin Resource Sharing	Browser-Regeln, die kontrollieren, welche Websites die API aufrufen dürfen
SSRF	Server-Side Request Forgery	Ein Angriff, bei dem ein Server ausgetrickst wird, interne URLs abzurufen — der URL-Import Endpoint schützt davor
MCQ	Multiple-Choice Question	Einer der beiden Quizfragen-Typen
KB	Knowledge Base	All deine eingelesenen, durchsuchbaren Dokumente

(Jede Behauptung in dieser Serie kann direkt im überprüft werden — die relevante Datei wird immer genannt, wenn es wichtig ist, und die Repository-README skizziert die komplette Architektur.)

Fazit

Nimm die Abkürzungen weg, und CogniVault ist ein kleines System: ein Webserver, eine Modell-Laufzeitumgebung, eine Haltbarkeits-Datenbank (Durability Database) und eine Handvoll Dateien. Die Raffinesse liegt nicht in der Anzahl der Teile — sie liegt darin, wie ein paar gut gewählte Teile zusammenarbeiten. Von dieser Zusammenarbeit handeln die nächsten drei Teile.

Als Nächstes: — wie ein 1.000-seitiges gescanntes PDF zu etwas wird, das die KI in Sekunden durchsuchen kann, und warum die Pipeline einen Absturz bei Seite 800 überlebt.

CogniVault Backend erklärt, Teil 2 · Von der Datei zum durchsuchbaren Wissen

Fri, 12 Jun 2026 00:00:00 +0000

Alle Abkürzungen werden im Anhang am Ende der Seite vollständig erklärt.

Ein LLM kann dein PDF nicht “öffnen”. Dieser Satz überrascht viele Neulinge, also lass uns das kurz sacken lassen: Wenn du in CogniVault mit deinen Dokumenten chattest, fasst das Modell die Originaldateien nie an. Es muss etwas zwischen “Ich habe eine Datei in den Browser gezogen” und “Die KI hat mir gerade Seite 47 zitiert” passieren.

Dieses Etwas nennt man Ingestion (Datenaufnahme), und darum geht es in diesem Teil. In haben wir das große Ganze skizziert; heute zoomen wir in einen bestimmten Bereich – das Fließband, das Dateien in durchsuchbares Wissen verwandelt.

Das Fließband

Stell dir die Ingestion wie ein Fließband mit vier Stationen vor:

Extrahieren: Den Text aus jeder Datei herausholen – auch aus gescannten.
Chunken (Zerlegen): Den Text in Stücke zerschneiden, die klein genug sind, um in einen Prompt zu passen.
Embedden (Einbetten): Jeden Chunk in einen Vektor (eine Liste von Zahlen, die seine Bedeutung einfängt) verwandeln, damit ähnliche Ideen im Vektorraum nah beieinander landen.
Speichern: Vektoren und Metadaten so ablegen, dass sie später durchsucht werden können.

flowchart TD A["Upload
POST /upload
gespeichert in docs/"] --> B subgraph WF["DBOS dauerhafter Workflow"] B["Schritt 1
Welche Dateien haben sich geändert?
SHA-256 Fingerabdrücke"] --> C["Schritt 2
Text extrahieren
pro Format + OCR-Fallback"] C --> D["Chunking
1000 Zeichen, 100 Überlappung"] D --> E["Schritt 3
Embedden
embeddinggemma, 5er-Batches"] E --> F["Schritt 4
Speichern
FAISS Index + Metadaten JSON"] end F --> G["In-Memory Index neu laden
sofort durchsuchbar"]

Ziemlich simpel. Die spannende Ingenieursarbeit steckt in den Fehlerfällen – fangen wir also damit an.

Das Kassenbuch der Fabrik: Warum die Pipeline keine Arbeit verlieren darf

Das Embedden einer großen Bibliothek dauert Minuten. Was passiert, wenn dein Laptop bei Seite 800 eines 1.000-seitigen Handbuchs in den Ruhezustand geht? Bei einem einfachen Python-Skript fängt alles wieder bei Seite 1 an.

CogniVault schreibt die Pipeline stattdessen als einen dauerhaften DBOS-Workflow. Stell dir eine Fabrik vor, in der jede Station einen dauerhaften Stempel in ein Kassenbuch drückt, sobald sie eine Kiste fertiggestellt hat. Fällt der Strom aus, baut niemand fertige Kisten neu zusammen – die Arbeiter lesen das Buch und machen beim ersten ungestempelten Eintrag weiter.

DBOS ist dieses Buch, und PostgreSQL ist das Papier, auf dem es geschrieben steht. Jede Station der Pipeline ist ein mit Checkpoints versehener Schritt; nach einem Neustart liefern abgeschlossene Schritte sofort ihre aufgezeichneten Ergebnisse zurück und die Ausführung geht beim ersten unfertigen Schritt weiter. Ein fehlgeschlagener Embedding-Batch wird einfach nochmal probiert.

Das ist auch der Mechanismus hinter der Live-Fortschrittsanzeige in der UI: Der Start einer Ingestion liefert eine workflow_id zurück, und das Frontend fragt regelmäßig einen Status-Endpoint ab, der meldet, welche Schritte abgeschlossen sind, welche laufen und welche noch warten.

Ich habe einen ausführlichen Deep-Dive über diesen Mechanismus geschrieben – inklusive dessen, was passiert, wenn du den Prozess mitten in der Ingestion mit kill -9 beendest – in .

Fingerabdrücke, kein Blindflug: SHA-256 Änderungserkennung

Deine komplette Bibliothek jedes Mal neu zu embedden, wenn du eine einzige Datei hinzufügst, wäre Verschwendung. Bevor also irgendwelche Arbeit passiert, berechnet die Pipeline für jede Datei einen SHA-256 Hash (einen Inhalts-Fingerabdruck – ändere ein Zeichen in der Datei, und der Fingerabdruck ändert sich komplett) und vergleicht ihn mit dem Fingerabdruck, der bei den vorhandenen Chunks der Datei gespeichert ist:

Noch nie gesehen → einlesen (ingest).
Fingerabdruck hat sich geändert → die alten Chunks werden soft-gelöscht und die Datei wird neu eingelesen.
Fingerabdruck identisch → komplett überspringen.

Warum “soft”-gelöscht? Weil der FAISS-Indextyp, den CogniVault nutzt, keine einzelnen Vektoren entfernen kann. Veraltete Chunks werden in den Metadaten einfach als deleted: true markiert; ihre Vektoren bleiben im Index, aber jede Suche filtert sie heraus. Das ist eine ehrliche, langweilige Lösung – und sie korrumpiert niemals den Index.

Jedes Format kriegt eine Sonderbehandlung

Hier ist ein Detail, das eine Demo von einem Produkt unterscheidet. Eine naive Pipeline extrahiert einfach “den ganzen Text” und macht dann Feierabend. Bei CogniVault bekommt jedes Format einen Extractor, der genau die Struktur beibehält, die das Retrieval später braucht:

Format	Strategie
PDF	Seite für Seite, wobei die Seitenzahlen behalten werden (diese werden später zu Quellenangaben). Jede Seite mit weniger als 50 Zeichen gilt als gescannt und wird an die OCR geschickt
Gescannte Seite	Die Seite wird mit etwa 144 dpi als Bild gerendert, dann extrahiert Tesseract OCR (Optical Character Recognition – Text aus Bildern auslesen) die Wörter
Markdown	Wird an Überschriften aufgeteilt; jeder Abschnitts-Chunk bekommt einen Breadcrumb-Präfix wie `[Section: Intro > Setup]`, damit sein Embedding die Dokumentenhierarchie in sich trägt
CSV	Zeilen werden in 20er-Gruppen gechunkt – und jeder Chunk bekommt die Kopfzeile vorangestellt, sodass das Modell immer die Spaltennamen kennt
Excel	Gleiches Zeilen-Gruppen-Prinzip pro Arbeitsblatt, mit dem Präfix `[Sheet: name]`
PowerPoint	Ein Chunk pro Folie
Word	Absätze plus Tabellenzellen
Webseiten	Werden bei Bedarf abgerufen und auf sauberen Artikeltext reduziert – geschützt durch einen SSRF-Guard (Schutz vor Server-Side Request Forgery: der Server weigert sich, private oder interne Adressen abzurufen)

Frag dich mal, warum das CSV-Detail wichtig ist. Wenn Chunk 14 eines Spreadsheets einfach nur zwanzig nackte Zahlenreihen enthält, wird keine Suche ihn jemals mit der Frage “Wie hoch war das Q3-Budget?” in Verbindung bringen. Stellst du die Kopfzeile voran, weiß der Chunk, dass er Budget-Spalten enthält. Struktur ist der Treibstoff fürs Retrieval.

Chunking: 1.000 Zeichen mit 100 Zeichen Sicherheitsnetz (Überlappung)

Lange Texte werden in Stücke von etwa 1.000 Zeichen zerlegt, wobei sich benachbarte Stücke um 100 Zeichen überlappen. Diese Überlappung ist eine Versicherung: Ein Satz, der genau an der Chunk-Grenze zerschnitten wird, taucht in einem der beiden Nachbarn immer noch als Ganzes auf, sodass keine Idee in die Lücke zwischen den Chunks fällt.

Embedden und Speichern

Chunks werden von embeddinggemma (via Ollama) in 5er-Batches embedded – jeder Chunk wird zu einem Vektor. Die Vektoren werden normalisiert und an einen FAISS-Index angehängt; daneben hält eine JSON-Datei für jeden Chunk den Quelldateinamen, die Seitenzahl, die Kategorie, den Fingerabdruck und den eigentlichen Text fest. Der Index speichert die Zahlen; das JSON speichert die Bedeutung.

Eine Designentscheidung, die man für Anfänger hervorheben sollte: Das hier ist ein exakter Index, kein approximativer. Viele Vektor-Datenbanken nutzen ANN (Approximate Nearest Neighbour)-Abkürzungen, die bei riesiger Skalierung ein wenig Genauigkeit gegen Geschwindigkeit tauschen. Im Maßstab einer persönlichen Bibliothek brauchst du diesen Kompromiss nicht – CogniVault prüft jeden Vektor bei jeder Suche und ist trotzdem schnell.

Die gesamte Reise, von Anfang bis Ende

%%{init: {'sequence': {'actorFontSize': 28, 'messageFontSize': 24, 'loopTextFontSize': 22, 'noteFontSize': 22}}}%% sequenceDiagram actor U as Du participant F as Frontend participant B as FastAPI participant W as DBOS Workflow participant O as Ollama (embeddinggemma) participant V as FAISS + Metadaten U->>F: Drag and Drop einer Datei, Kategorie wählen F->>B: POST /upload B->>B: Typ und Größe validieren, in docs/ speichern F->>B: POST /ingest B->>W: Dauerhaften Workflow starten B-->>F: workflow_id loop Status abfragen F->>B: GET /ingest/status/{workflow_id} B-->>F: Schrittliste (steuert die Fortschrittsanzeige) end W->>W: SHA-256 Änderungserkennung W->>W: Text extrahieren (pro Format, OCR falls gescannt) W->>W: Chunking (1000 Zeichen / 100 Überlappung) W->>O: Embedden in 5er-Batches O-->>W: Vektoren W->>V: Vektoren + Metadaten anhängen B-->>F: SUCCESS — Index neu geladen F-->>U: "Wissens-Sync abgeschlossen"

Fazit

Bei der Ingestion entscheidet sich meistens die eigentliche RAG-Qualität – lange bevor irgendwelches clevere Prompting ins Spiel kommt. Beibehaltene Seitenzahlen, Header, die in jeden Spreadsheet-Chunk kopiert werden, gerettete Scans durch OCR, und ein Kassenbuch, das das Ganze absturzsicher macht: Nichts davon ist glamourös, aber alles davon zeigt sich später in Form von Antworten, die die richtige Seite zitieren.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
LLM	Large Language Model	Ein neuronales Netz, trainiert mit riesigen Textmengen, das Sprache lesen und erzeugen kann
DBOS	Database-Oriented Operating System	Die Bibliothek, die Workflow-Schritte in PostgreSQL sichert, damit abgestürzte Jobs fortgesetzt werden können
SHA-256	Secure Hash Algorithm, 256-bit	Ein Inhalts-Fingerabdruck – ändere ein Byte einer Datei und der Hash ändert sich komplett
OCR	Optical Character Recognition	Text aus Bildern lesen – der Rettungsweg für gescannte PDF-Seiten
SSRF	Server-Side Request Forgery	Ein Angriff, bei dem ein Server ausgetrickst wird, interne URLs abzurufen; der URL-Importer blockiert dies
FAISS	Facebook AI Similarity Search	Der Vektor-Index, an den die Embeddings angehängt werden
ANN	Approximate Nearest Neighbour	Die Genauigkeit-gegen-Geschwindigkeit-Abkürzung, die CogniVault absichtlich nicht nimmt
dpi	Dots Per Inch	Bildauflösung – gescannte Seiten werden vor der OCR mit ca. 144 dpi gerendert
JSON	JavaScript Object Notation	Das Format der Chunk-Metadaten-Datei neben dem FAISS-Index
PDF / CSV	Portable Document Format / Comma-Separated Values	Zwei der acht+ unterstützten Dateiformate
API	Application Programming Interface	Die Endpoints (`/upload`, `/ingest`, `/ingest/status/…`), die den Ablauf steuern

Als Nächstes: — hybrides Retrieval, der 6-Tools-Agent und der 2-Phasen-Stream, der zeigt, wie das Modell denkt, bevor es antwortet.

CogniVault Backend erklärt, Teil 3 · Wie aus einer Frage eine belegte Antwort wird

Fri, 12 Jun 2026 00:00:00 +0000

Alle Abkürzungen werden im Anhang am Ende der Seite vollständig erklärt.

Du tippst eine Frage ein. Ein paar Sekunden später bekommst du eine Antwort mit Fußnoten — genaue Angabe der Dokumente und Seiten, aus denen sie stammt. Dieser Teil geht alles durch, was dazwischen passiert.

In haben wir die Wissensbasis aufgebaut: jedes Dokument gechunkt, embedded und indiziert. Jetzt fangen wir an, sie zu nutzen — und hier hört CogniVault auf, nur eine Pipeline zu sein, und fängt an, spannend zu werden.

Zwei Bibliothekare, weil einer dich immer wieder hängen lässt

Stell dir eine Bibliothek vor mit einer Bibliothekarin, die alles nach Vibes ordnet. Frag sie nach “Prozeduren bei Server-Ausfall” und sie ist genial — sie versteht, was du meinst, und findet Dokumente, die das Konzept diskutieren, egal welche Wörter sie benutzen. Aber frag sie nach “Fehlercode 404B”, zuckt sie mit den Schultern und reicht dir allgemeine Netzwerk-Guides. Mit exakten Zeichenketten kann sie nichts anfangen.

Am Ende des Flurs sitzt ein zweiter Bibliothekar mit einem Zettelkasten. Er findet den genauen String “404B” sofort — aber stell ihm eine konzeptionelle Frage, die anders formuliert ist als im Quelltext, und er findet überhaupt nichts.

Das sind die zwei Hälften der Suche:

Semantische Suche (FAISS) — deine Frage wird in einen Vektor umgewandelt (embedded), und der Index findet Chunks, deren Vektoren in die gleiche Richtung zeigen (technisch gesehen: Cosinus-Ähnlichkeit — wie gut zwei Pfeile übereinstimmen). Super für die Bedeutung, blind für exakte Identifikatoren.
Keyword-Suche (BM25) — eine Bewertungsformel (Scoring), die Chunks belohnt, die deine exakten Wörter enthalten, gewichtet danach, wie markant diese Wörter sind. Super für Identifikatoren, blind für Synonyme.

CogniVault fragt jedes Mal beide Bibliothekare, und verschmilzt dann ihre Antworten mit Reciprocal Rank Fusion (RRF) — einer Formel, die gerankte Listen kombiniert, indem sie nur die Positionen nutzt:

score(chunk) = summe aus beiden Listen von 1 / (60 + rang)

Ein Chunk, der von einem der beiden Bibliothekare hoch gerankt wird, punktet gut; ein Chunk, den beide gut fanden, schwimmt ganz nach oben. Die Eleganz liegt darin, was fehlt: Du musst niemals die Ähnlichkeits-Scores von FAISS mit der komplett anderen Skala von BM25 abgleichen, weil Ränge (Ranks) der einzige Input sind. Die Konstante 60 stammt direkt aus dem ursprünglichen Research-Paper von 2009, und ja, sie ist auch im Code zitiert.

Ein paar Implementierungsdetails, die du kennen solltest: Beide Suchen holen absichtlich zu viel (mindestens 20 Kandidaten jeweils), damit die Fusion Material zum Arbeiten hat; sehr schwache semantische Treffer werden fallengelassen, aber ein perfekt auf Keywords passender Chunk kann durch die Fusion trotzdem noch gerettet werden; und die finale Antwort nutzt die Top-7-Chunks. Ich habe dieses ganze Setup in gegen eine reine Vektorsuche gebenchmarkt, falls du die Kriegsgeschichten dazu lesen willst.

Der Agent: Ein Modell, das selbst entscheidet

Hier ist der zweite Punkt, der Anfänger oft ins Straucheln bringt: Der Chat von CogniVault ist nicht einfach “Kopiere Chunks in einen Prompt, bekomme eine Antwort.” Es ist ein Agent — ein Modell, das in einer Schleife läuft, in der es sich entscheiden kann, Tools aufzurufen, deren Ergebnisse zu lesen und erst dann zu antworten.

Gebaut mit dem Strands Agents SDK, bekommt der Agent sechs Tools:

Tool	Aufgabe
`search_knowledge_base`	Das Kern-RAG-Tool — führt die hybride Suche von oben aus, liefert Chunks mit Quelle und Seite zurück
`list_documents`	Nachschauen, was im Vault (Tresor) liegt
`analyze_document`	Strukturierte Analyse eines Dokuments: Themen, Entitäten, Fakten, Zusammenfassung
`compare_documents`	Beantwortung einer Frage durch den direkten Vergleich von zwei Dokumenten
`calculator`	Sicheres Rechnen — der Ausdruck wird in einen Syntaxbaum (AST) geparst und nur erlaubte Operatoren werden ausgeführt. Niemals `eval()`
`current_time`	Datum und Uhrzeit

Es gibt hier kein fest programmiertes Routing. Das Modell liest deine Frage und entscheidet, welche Tools es aufruft, geleitet von seinem System-Prompt. Fragst du “Vergleiche die zwei Verträge hinsichtlich der Kündigungsklauseln”, greift es zum compare_documents; fragst du “Was sind 15% von 2.340”, nutzt es den Taschenrechner, anstatt Mathematik zu halluzinieren.

Zwei Sicherheitsdetails, auf die Anfänger achten sollten, weil sie den Unterschied zwischen einem Spielzeug und einem Produkt ausmachen: Für jeden Request wird ein frischer Agent gebaut (kein geteilter State, der zwischen parallelen Chats überspricht), und die Dokumentenanalyse-Tools rufen das Modell direkt auf statt über den Agenten — sonst könnte ein Agent, der ein Tool aufruft, das wiederum den Agenten aufruft, in einer Endlosschleife feststecken.

Dem Modell beim Denken zusehen

Wenn du eine Nachricht absendest, streamt die Antwort als NDJSON (Newline-Delimited JSON — jede Zeile des Streams ist ein eigenes kleines JSON-Objekt). Und das passiert in zwei Phasen:

Phase 1 — Denken. Gemmas Argumentationskette (Reasoning Chain) streamt zuerst und wird im aufklappbaren Panel über der Antwort gerendert. Es ist absichtlich so gebaut, dass es nicht zwingend klappen muss (Best-Effort): Falls es aus irgendeinem Grund fehlschlägt, kommt die Antwort trotzdem.

Phase 2 — Die Agenten-Antwort. Tools laufen, Zitate (Quellenangaben) tauchen im Quellen-Panel auf, sobald die Suche abgeschlossen ist — bevor die Antwort fertig geschrieben ist — und der Antworttext streamt herein.

flowchart TB Q["Deine Frage
(plus optionale Bilder, Dateien, Scope)"] --> P1 subgraph STREAM["POST /rag — ein NDJSON-Stream"] P1["Phase 1: Denken
Reasoning-Chunks streamen zuerst"] P1 --> P2["Phase 2: Agent
frisch pro Request, Historie wiederhergestellt"] P2 -->|"entscheidet sich aufzurufen"| T["search_knowledge_base"] T --> D["FAISS
semantisch"] T --> S["BM25
Keywords"] D --> RRF["RRF Fusion — Top 7 Chunks"] S --> RRF RRF -->|"Chunks + Quellenangaben"| P2 P2 --> OUT["Quellenangaben, dann Antworttext,
dann ein Speicher-Nutzungs-Report"] end

Jede Zeile im Stream ist typisiert: thinking, metadata (eine Quelle/Zitat), text (Antwort), memory (wie voll das Konversations-Budget ist) oder error. Das Frontend liest einfach die Zeilen und leitet sie in das richtige Panel weiter. Ich habe dieses Design zerlegt — und erklärt, warum das Denken vor den Tool-Aufrufen kommt — in .

Ein Speicher-Budget, kein fassloses Loch

Gemmas Context Window (die Textmenge, die das Modell auf einmal betrachten kann) beträgt 128K Token, aber CogniVault lässt den Chatverlauf nicht über das komplette Fenster wuchern. Jede Chat-Session bekommt ein Budget von 48.000 Zeichen — grob 12.000 Token. Überschreitest du es, fällt das älteste Frage-Antwort-Paar leise als erstes heraus. So bleibt der Großteil des Fensters frei für das, was wirklich zählt: deine aktuelle Frage und die abgerufenen Chunks.

Zwei Resilienz-Tricks, die du für deine eigenen Projekte klauen solltest:

Reboots überleben. In-Memory-Verlauf stirbt mit dem Prozess. Deshalb baut die erste Nachricht in einer Session nach einem Backend-Neustart ihren Verlauf aus dem Chat-Log wieder auf, den das Frontend persistiert hat. Multi-Turn-Gedächtnis überlebt Neustarts.
Bearbeiten und neu generieren. Wenn du eine frühere Nachricht bearbeitest, wird der gespeicherte Verlauf auf genau diesen Punkt zurückgespult, bevor neu gefragt wird — das Modell vergisst buchstäblich die Zeitlinie, die jetzt nicht mehr existiert.

Scope: Die KI auf bestimmte Dokumente festnageln

Noch ein letztes Feature, und eine Lektion über kleine lokale Modelle. Du kannst einen Chat auf bestimmte Dateien oder eine Kategorie pinnen (Scope). Dieser Filter reist mit dem Request und eine zwingende Such-Anweisung wird sowohl in den System-Prompt als auch in deine eigentliche Nutzer-Nachricht injiziert.

Warum in beide? Weil kleine Modelle manchmal Anweisungen ignorieren, die nur im System-Prompt stehen — aber sie können nicht ignorieren, was direkt in der Frage steckt. Gürtel und Hosenträger. Wenn du mit 4-Milliarden-Parameter-Modellen arbeitest statt mit den größten Frontrunnern, lernst du, Anweisungen so zu platzieren, dass man sie unmöglich übersehen kann, anstatt nur zu hoffen, dass sie befolgt werden.

Fazit

Eine belegte Antwort ist das Zusammenspiel von vier Systemen: Zwei Retriever decken gegenseitig ihre blinden Flecken ab, eine Fusionsformel, die nichts weiter braucht als Ränge, ein Agent, der sich seine Tools selbst aussucht, und ein Stream, der seinen Lösungsweg offenlegt. Keines der vier ist für sich genommen exotisch — das eigentliche Produkt ist ihre Zusammenarbeit.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
RAG	Retrieval-Augmented Generation	Hole erst relevante Passagen aus deinen eigenen Dokumenten; lass das Modell daraus antworten
FAISS	Facebook AI Similarity Search	Die semantische (bedeutungsbasierte) Hälfte der hybriden Suche
BM25	Best Match 25	Die Keyword-Hälfte — eine klassische Ranking-Formel aus dem Okapi Information-Retrieval-System
RRF	Reciprocal Rank Fusion	Vereint die beiden gerankten Listen und nutzt dafür nur den Rang jedes Chunks: `score = Σ 1/(60 + rang)`
NDJSON	Newline-Delimited JSON	Ein Stream, bei dem jede Zeile ein eigenes komplettes JSON-Objekt ist — das Format der Chat-Antwort
JSON	JavaScript Object Notation	Das universelle Textformat für strukturierte Daten
AST	Abstract Syntax Tree	Die geparste Form eines Ausdrucks — wie der Taschenrechner rechnet, ohne `eval()` zu nutzen
LLM	Large Language Model	Ein neuronales Netz, trainiert mit riesigen Textmengen, das Sprache lesen und erzeugen kann
SDK	Software Development Kit	Eine Bibliothek von Bausteinen — hier Strands, das die Agenten-Schleife bereitstellt
K (in 128K)	Kilo (Tausend)	128K Token ≈ 128.000 Token — Gemmas Context Window

Als Nächstes: — die gleiche Maschinerie, aber ausgerichtet auf das Erstellen von Quizzes, Workshops, Karteikarten und Mindmaps, plus eine Tabelle mit jedem Byte, das die App speichert und wo genau es lebt.

Teil 1 · CogniVault Architektur: Warum Standard-RAG nicht reicht (Hybride Suche)

Mon, 01 Jun 2026 00:00:00 +0000

Alle Abkürzungen werden im Anhang am Ende der Seite ausführlich erklärt.

Vektorsuche ist der Prozess, bei dem die ähnlichsten Elemente in einem Datensatz basierend auf ihren Vektor-Embeddings gefunden werden. So funktionieren RAG-Systeme normalerweise. Aber was passiert, wenn du die ähnlichsten Elemente in einem Datensatz nicht nur aufgrund ihrer semantischen Bedeutung, sondern auch anhand des exakten Wortlauts der Suchanfrage finden musst?

Das wird kritisch, wenn die Information, die du suchst, nicht nur inhaltlich verwandt sein soll, sondern genau mit einer bestimmten Zeichenkette oder einem bestimmten Schlüsselwort übereinstimmen muss.

Zwei Wege, ein Buch zu finden

Stell dir eine gute lokale Buchhandlung vor. Die Besitzerin hat alles gelesen und empfiehlt nach Gefühl. Sag ihr, dass du Der Marsianer geliebt hast, und sie gibt dir Project Hail Mary — anderer Titel, andere Handlung, aber dieselbe DNA: ein einsamer Wissenschaftler, ein unmögliches Überlebensproblem, Witze unter Druck. Frag nach “sowas wie Stolz und Vorurteil” und du gehst mit Emma raus. Sie gleicht keine Wörter ab. Sie gleicht Bedeutung ab.

Nun stell ihr eine andere Art von Frage: “Ich brauche das Buch mit der ISBN 978-0-553-41802-6” oder “das Handbuch, auf dessen Cover der Fehlercode 404B erwähnt wird.” Ihre Superkraft ist hier nutzlos. Keine noch so große literarische Intuition findet einen exakten String. Dafür gehst du zur Kasse und schaust in den Katalog — einen langweiligen, wörtlichen Index, der genau weiß, welches Regal welche Kennung enthält, und dem “Vibes” völlig egal sind.

Eine gut geführte Buchhandlung braucht beides. Genauso wie ein gut geführtes RAG-System:

FAISS — Facebook AI Similarity Search (die belesene Besitzerin): ein Vektorindex, der Textabschnitte findet, deren Bedeutung mathematisch nah an deinem Prompt liegt. Genial für “Wie ist die praktische Prüfung aufgebaut?”, aber blind für “§3 Absatz 2”.
BM25 — Best Match 25 (der Katalog): ein klassischer Keyword-Scoring-Algorithmus, der exakte Worttreffer belohnt, gewichtet danach, wie selten und markant diese Wörter sind. Genial für Identifikatoren und zitierte Phrasen, aber blind für Umschreibungen (Paraphrasen).

CogniVault führt bei jeder Suche beide Retriever aus — das nennt man Hybride Suche (Hybrid Search) — und führt dann die beiden Ranglisten mit einer Formel namens Reciprocal Rank Fusion (RRF) zusammen. RRF bewertet jeden Chunk rein nach seiner Position in jeder Liste: Ein Chunk, der von einem der beiden Retriever hoch eingestuft wird, schneidet gut ab, und ein Chunk, bei dem sich beide Retriever einig sind, steigt nach ganz oben. Da nur Ränge verwendet werden, müssen die inkompatiblen Bewertungsskalen der beiden Retriever niemals in Einklang gebracht werden.

Der Agent entscheidet, wann gesucht wird

Hier ist der Teil, den die meisten Diagramme verdrehen (meins in einem früheren Entwurf eingeschlossen): Das Retrieval (die Abfrage) passiert nicht, bevor das Modell ins Spiel kommt. Es passiert innerhalb des eigenen Loops des Modells.

CogniVault verpackt Gemma im Strands Agents SDK. Das Modell erhält deine Frage zusammen mit einer Reihe von Tools (vorgeschriebene Python-Funktionen wie search_knowledge_base, calculator oder compare_documents). Es denkt dann über die Frage nach und entscheidet selbst, ob — und welche — Tools es aufruft. Bei den meisten Fragen zu Dokumenten ruft es search_knowledge_base auf, liest die abgerufenen Chunks und schreibt erst dann seine Antwort, basierend auf dem, was es gefunden hat.

Hier ist die Blaupause der Architektur dieses Loops:

graph TD Client[📱 Nutzer-Anfrage] --> App[🖥️ FastAPI Server] subgraph AgentLoop["Der Strands Agent-Loop (powered by Gemma 4)"] App --> Agent[🧠 Agent analysiert die Frage] Agent -->|Entscheidet zu suchen| Search[search_knowledge_base] subgraph HybrideSuche ["Hybride Such-Engine"] Search -->|Semantisch| FAISS[(FAISS Vektor)] Search -->|Exakter Treffer| BM25[(BM25 Keyword)] FAISS --> RRF{RRF Fusion} BM25 --> RRF end RRF -->|Beste Chunks + Quellenangaben| Agent Agent -->|Fundierte Antwort| Answer[Gestreamte Antwort] end Answer --> Client

Eine Feinheit, die erwähnenswert ist: Der Agent ist Gemma. Es gibt am Ende kein separates “Formatierungsmodell” — dasselbe Modell, das sich für die Suche entschieden hat, schreibt auch die endgültige Antwort, nun mit den abgerufenen Chunks vor Augen.

Was kommt als Nächstes?

Eine Spielzeug-RAG-App zu bauen ist einfach, aber eine zu bauen, die tatsächlich genau das Dokument abruft, das du brauchst, erfordert hybride Engines und einen Agenten, der weiß, wann er sie einsetzen muss.

Willst du sehen, wie dieses System riesige Dokumente sicher einliest, ohne Arbeit zu verlieren, wenn mal etwas abstürzt? Lies Teil 2: Dauerhafte Ingestion mit DBOS

Oder, wenn du lieber direkt in den Code springen willst: Die hybride Suche befindet sich in backend/services/vector_db.py des .

Anhang: Abkürzungen in diesem Beitrag

Abbreviation	Full form	Meaning
RAG	Retrieval-Augmented Generation	Rufe zuerst relevante Passagen aus deinen eigenen Dokumenten ab; lass das Modell daraus antworten anstatt aus dem Trainingsgedächtnis
FAISS	Facebook AI Similarity Search	Metas Bibliothek zum Speichern von Vektoren und zum schnellen Finden der ähnlichsten
BM25	Best Match 25	Eine Keyword-Ranking-Formel — die 25. Ranking-Funktion, die im Okapi-Information-Retrieval-System entwickelt wurde
RRF	Reciprocal Rank Fusion	Eine Formel, die mehrere Ranglisten nur anhand des Rangs jedes Elements zusammenführt: `score = Σ 1/(k + rank)`
LLM	Large Language Model	Ein auf riesigen Textmengen trainiertes neuronales Netzwerk, das Sprache lesen und erzeugen kann
SDK	Software Development Kit	Eine Bibliothek mit Bausteinen — hier Strands, was den Agent-Loop bereitstellt
API	Application Programming Interface	Die URLs, die das Frontend aufruft, um mit dem Backend zu kommunizieren
ISBN	International Standard Book Number	Die eindeutige Kennung, die auf jedem veröffentlichten Buch gedruckt ist — der beste Freund des Katalogs

Gemma CogniVault

Mon, 25 May 2026 00:00:00 +0000

Überblick

Gemma CogniVault ist ein zu 100 % lokaler, auf Privatsphäre ausgerichteter KI-Lernbegleiter. Deine Dokumente bleiben auf deiner Hardware. Die Inferenz läuft über Ollama auf localhost. Keine Telemetrie, keine Embeddings an Dritte geschickt, keine Ausnahmen. Ein Live Privacy Vault Audit Panel bestätigt dir zur Laufzeit, dass es null externe Verbindungen gibt.

Und es ist auch wirklich fähig — die volle Bandbreite von Gemma 4 (Completion, Vision, Tools, Reasoning) läuft auf deinem Laptop, verpackt in eine App, die deine Dokumente in Quizzes, Multi-Lektionen-Workshops, Karteikarten-Decks und visuelle Mindmaps verwandelt, komplett mit einem Dashboard für deinen Lernfortschritt und 25 Achievement-Badges.

Was drinsteckt

Schicht	Technologie
LLM & Embeddings	Ollama · `gemma4:e4b` · `embeddinggemma`
Agent Framework	Strands Agents SDK
Backend	FastAPI · Python 3.10+ · Pydantic
Vector Search	FAISS IndexFlatIP + BM25Okapi · Reciprocal Rank Fusion
Document Parsing	pypdf · python-docx · python-pptx · openpyxl · trafilatura
OCR	pytesseract · pymupdf · Pillow
Audio	faster-whisper
Workflow Engine	DBOS + PostgreSQL
Frontend	React 19 · TypeScript · Vite · Tailwind v4 · Framer Motion · TanStack Query

Vier Bereiche

Bereich	Wofür es da ist
💬 Chat	Frag alles über deine Dokumente. Zitierte Antworten, Scope-Filter, Spracheingabe, Anhänge.
📚 Knowledge Base	Hochladen, kategorisieren und verwalten deiner Dokumente. SHA-256 Änderungserkennung beim erneuten Upload.
🎓 Study Hub	Vier KI-gestützte Lernmodi: Quiz · Workshop · Flashcards · Mindmaps.
📊 Dashboard	Gesamte Lernzeit, aktueller Streak, 25 Achievement-Badges, 90-Tage-Aktivitäts-Heatmap.

Highlights

🧠 Thinking Mode — ein ausklappbares Reasoning-Panel streamt Gemmas Chain-of-Thought vor der Antwort
🔍 Hybrid Retrieval — FAISS dense + BM25 keyword kombiniert durch Reciprocal Rank Fusion
🖼️ Multimodal — Bilder, PDFs und DOCX-Dateien direkt im Chat anhängen
🛟 Durable workflows — DBOS-gesicherte Ingestion; crash-resistent und wiederaufnehmbar
🏆 25 Achievement-Badges — automatisch getrackt in Chat, Quizzes, Workshops, Flashcards, Mindmaps
🔒 Vault Audit Panel — Live-Indikator für “null externe Verbindungen”

Darüber schreiben

Ich veröffentliche eine Serie von Posts, die die technischen Entscheidungen hinter CogniVault auspacken — das Privacy-Framing, den Retrieval-Stack, die Agenten-Loop, die Langlebigkeit bei der Ingestion, wie man JSON aus einem lokalen Modell kriegt, wie man Mindmaps ohne Graph-Bibliothek zeichnet, den Gamification-Layer und wie die Test-Suite komplett ohne Infrastruktur auskommt.

Sieh dir den für die komplette Serie an.

Probier es aus

git clone https://github.com/ndimoforaretas/local-gemma-rag.git
cd local-gemma-rag
./scripts/setup.sh # one-time
./scripts/start.sh

Dann öffne .

Teil 4 · Crash-Resumable Ingestion: DBOS, SHA-256 und wie man ein kill -9 überlebt

Tue, 05 May 2026 00:00:00 +0000

Teil einer Serie über den Bau von . Zuvor: .

Alle Abkürzungen werden im Anhang am Ende der Seite ausführlich erklärt.

Es gibt zwei Dinge, die deine RAG-Ingestion-Pipeline auf keinen Fall tun sollte:

Ein 200-seitiges PDF neu einbetten, weil du einen Tippfehler auf Seite 12 korrigiert hast.
Ihren Fortschritt verlieren, wenn du auf halber Strecke den Laptop zuklappst.

Das Erste verschwendet Zeit und Rechenressourcen. Das Zweite führt zu Misstrauen in das System. Beides hat denselben Ursprung: Die Ingestion wird wie eine Fire-and-Forget-Funktion behandelt, obwohl sie eigentlich eine lang laufende Pipeline ist, deren Zwischenzustände es wert sind, erhalten zu bleiben.

CogniVault behandelt Ingestion als einen Durable Workflow. Genauer gesagt als einen -Workflow, der in Postgres mit Checkpoints versehen ist und Content-Hashing für inkrementelle Arbeit nutzt. In diesem Beitrag schauen wir uns beides an.

Die Pipeline

1. Scan docs/ → SHA-256 hash per file
 ├── New file → queue for embedding
 ├── Changed file → soft-delete old chunks, re-embed
 └── Unchanged → skip (idempotent)

2. Extract text → per-format extractor (PDF/OCR, DOCX, PPTX, XLSX, MD, CSV, TXT, HTML)
3. Chunk → RecursiveCharacterTextSplitter (1000 chars, 100 overlap)
4. Embed → embeddinggemma via Ollama, batches of 5
5. Save → append to FAISS IndexFlatIP + JSON metadata on disk

Die rechenintensiven Stufen laufen als DBOS-Schritte innerhalb eines übergeordneten Workflows und sind alle mit Checkpoints versehen: Wenn der Prozess zwischen den Schritten stirbt, macht der nächste Start genau beim letzten abgeschlossenen Schritt weiter.

SHA-256 als einzige Quelle der Wahrheit

Der naive Ansatz ist, die Ingestion anhand des Dateinamens zu verfolgen. Das geht genau dann schief, wenn jemand eine Datei direkt bearbeitet. Der Dateiname ist derselbe; der Inhalt nicht. Der Vector-Store schleppt dann klammheimlich veraltete Chunks mit sich herum.

Die Lösung ist inhaltsadressiert: Hashe die Datei-Bytes und speichere den Hash zusammen mit den Chunks. Bei jedem Ingestion-Durchlauf passiert Folgendes:

current_hash = hashlib.sha256(file_bytes).hexdigest()
stored_hash = chunk_metadata_for(filename).get("file_hash")

if stored_hash is None:
 schedule_ingest(filename) # new file
elif stored_hash == current_hash:
 skip(filename) # unchanged
else:
 soft_delete_chunks_for(filename) # changed
 schedule_ingest(filename)

Das verleiht der Ingestion eine idempotente Eigenschaft, die Gold wert ist: Die Pipeline zweimal hintereinander laufen zu lassen, bewirkt beim zweiten Mal fast nichts. Das ist nicht nur eine Optimierung — erst dadurch wird der nächste Abschnitt überhaupt möglich.

DBOS-Workflows

ist eine Python-Bibliothek, die normale Funktionen in Checkpoint-basierte Workflows verwandelt, die von Postgres gestützt werden. Das Modell ist kinderleicht: Dekoriere eine Funktion mit @DBOS.workflow(), markiere jeden lang laufenden Aufruf darin als @DBOS.step(), und DBOS speichert während der Ausführung für jeden Schritt Input, Output und Status in Postgres.

Wenn der Workflow abstürzt — Prozess gekillt, OS-Reboot, Abbruch der Postgres-Verbindung — sieht der nächste Start, dass ein unvollendeter Workflow mit derselben ID existiert, spielt die aufgezeichneten Schritt-Outputs aus Postgres ab (ohne sie neu auszuführen) und macht beim ersten unvollständigen Schritt weiter.

Hier ist die eigentliche Schrittstruktur (leicht vereinfacht aus backend/services/ingest.py):

@DBOS.workflow()
def ingest_workflow() -> int:
 filenames = list_document_files() # @DBOS.step — scan + hash check
 docs = []
 for name in filenames:
 docs += process_single_document(name) # @DBOS.step — extract text, one file each
 chunks = chunk(docs) # plain Python — fast, re-runs freely
 embeddings = []
 for batch in batches_of_5(chunks):
 embeddings += embed_batch(batch) # @DBOS.step — the slow one, retried on failure
 save_vector_store(embeddings, chunks) # @DBOS.step — append to FAISS + metadata
 return len(chunks)

Die Granularität von @DBOS.step entspricht der Granularität der Crash-Recovery und wurde bewusst so gewählt. Die Extraktion ist ein Schritt pro Datei, sodass bei einem Absturz während Datei 9 von 10 die ersten acht nicht neu gelesen werden. Embedding ist ein Schritt pro Batch von fünf Chunks, und zwar aus einem bestimmten Grund: embed_batch ist der langsame Part. Wenn der Laptop während der Embeddings den Geist aufgibt, setzen wir den Embedding-Loop beim fehlgeschlagenen Batch fort, nicht bei der PDF-Extraktion.

Fällt dir auf, was kein Schritt ist? Das Chunking. Text aufzuteilen ist schnelle, reine Python-Arbeit — es mit Checkpoints zu versehen, würde mehr Buchhaltung im Ledger kosten, als es bei einer Fortsetzung einfach neu zu machen.

In der Batch-Größe verbirgt sich noch ein kleiner Trick. DBOS speichert den Output jedes Schritts in Postgres, und embed_batch gibt seine Vektoren zurück — also enthält jeder Ledger-Eintrag Float-Werte für fünf Embeddings. Kleine Batches halten jeden Checkpoint-Datensatz klein und jeden erneuten Versuch (Retry) günstig. Ein riesiger “Bette alles ein”-Schritt würde eine riesige Ledger-Zeile und null Resume-Granularität bedeuten.

Die Format-Extraktoren

Schritt 2 (process_single_document) ist eine Weiche basierend auf der Dateiendung. Jeder Extraktor ist klein und einleuchtend; die interessanten Entscheidungen liegen in der Chunking-Strategie, die jeder nachgelagert füttert.

Format	Library	Chunking note
PDF	`pypdf` Seite für Seite; `pytesseract` OCR-Fallback für Bild-Seiten	Rekursiver Splitter, 1000/100
DOCX	`python-docx` (Absätze + Tabellenzeilen als Text verbunden)	Rekursiver Splitter
PPTX	`python-pptx`	Ein Chunk pro Folie (Titel + Body-Text)
XLSX	`openpyxl`	Header + 20-Zeilen-Batches, pro Arbeitsblatt
MD	`MarkdownHeaderTextSplitter`	Ein Chunk pro H1/H2/H3-Abschnitt, Breadcrumbs davor
CSV	Manueller Reader	Header-Zeile + 20-Zeilen-Batches
TXT	Rohes UTF-8 Lesen	Rekursiver Splitter
HTML	`trafilatura` sauberer Text	Rekursiver Splitter

Der OCR-Fallback ist es wert, kurz innezuhalten. PDFs gibt es in zwei Ausführungen: solche mit einer echten Textebene und solche, die im Grunde nur gescannte Bilder in einem PDF-Kostüm sind. pypdf liefert für die zweite Sorte nichts Brauchbares zurück, wirft aber auch keinen Fehler — es gibt einfach leere Strings zurück. Ohne ein Fallback lügt dich dein “Ingestion erfolgreich”-Log an.

Der Detektor ist eine Heuristik: Wenn pypdf weniger als 50 Zeichen für eine Seite zurückgibt, leite die Seite durch pymupdf → Pillow → pytesseract OCR. Langsamer, aber es produziert immerhin Text. Der Schwellenwert ist so eingestellt, dass er sensibel genug ist, um gescannte Seiten abzufangen, ohne legitimerweise kurze Seiten (wie ein Kapitel-Deckblatt oder ein Impressum) zu bestrafen.

Soft Delete, nicht Hard Delete

Wenn sich eine Datei ändert und wir sie neu einlesen, müssen die alten Chunks weg. Es ist verlockend, sie physisch aus dem FAISS-Index zu entfernen, aber FAISS IndexFlatIP unterstützt kein effizientes Löschen — du müsstest ihn neu aufbauen.

Stattdessen Soft Delete: Bei geänderten Dateien werden die alten Chunks in den Metadaten mit einem deleted: true-Flag markiert; neue Chunks werden ohne Flag angehängt. Bei einer Suchanfrage wird nach diesem Flag gefiltert, sodass veraltete Vektoren völlig harmlos im Index liegen bleiben. Wenn sich jemals genug totes Gewicht ansammelt, ist das Ventil offensichtlich — bau den Index nur mit aktiven Chunks neu auf —, aber in der Praxis habe ich das noch nie gebraucht.

Das ist dasselbe Muster, das die meisten Append-only-Systeme verwenden. Es passt natürlich perfekt zum Content-Hashing — Markieren-und-Anhängen ist viel billiger als Entfernen-und-Neubauen. Eine Feinheit dabei: Der Keyword-Index muss mitziehen. CogniVaults VectorDB.delete_by_source() setzt die Flags und baut BM25 neu auf, und zwar über die verbleibenden aktiven Chunks, sodass sich die beiden Retriever nie uneinig darüber sind, was eigentlich existiert.

Was der User sieht

Das Starten einer Ingestion (POST /ingest) liefert eine workflow_id zurück, und das Frontend fragt regelmäßig GET /ingest/status/{workflow_id} ab, um eine Live-Timeline der Workflow-Schritte zu zeichnen — Scannen, Extraktion pro Datei (“Lese Seiten… 3 von 21”), Einbetten (“Kalibriere Batch 4 von 12”), Speichern. Wenn der User den Tab mitten in der Ingestion schließt, fünf Minuten später wiederkommt und ihn neu öffnet — der Workflow ist im Hintergrund sowieso fertig gelaufen. Der nächste Aufruf von GET /api/vault/stats spiegelt die neue Chunk-Anzahl wider. Kein “Klicken zum Fortsetzen”-Button, kein manueller Recovery-Tanz.

Als ich das erste Mal mitten im Einbetten den Deckel zugeklappt habe und dann beim Aufwecken zusehen konnte, wie der Workflow sich den nächsten Schritt geschnappt und einfach weitergemacht hat, war ich, ehrlich gesagt, ein bisschen stolz. Das ist genau die Eigenschaft, die ich wollte, und das mit überraschend wenig Code.

Fallstricke und Randfälle

Ein paar Dinge, die ich auf die harte Tour lernen musste:

Mach embed_batch nicht zu groß. Ollama ist nicht besonders gut im Umgang mit Backpressure. Batches von 5 sind ein Sweetspot für embeddinggemma auf einer Maschine mit 16 GB RAM — größere Batches bleiben am Speicher hängen, kleinere verschwenden Overhead für die Round-Trips. (Und wie oben erwähnt: Die Batch-Größe bestimmt gleichzeitig die Größe deines Checkpoint-Datensatzes.)
Sei vorsichtig beim Löschen von Dateien. Soft-gelöschte Chunks müssen auch aus dem Korpus von BM25 verschwinden, sonst liefert die Keyword-Suche weiterhin Text, den die Dense Search (Vektorsuche) gar nicht mehr sieht. Wenn du BM25 innerhalb von delete_by_source() neu aufbaust, bleiben die beiden im Gleichschritt.
OCR ist langsam. Ein 50-seitiger Scan kann eine Minute oder länger dauern. Mach diese Wartezeit für den User sichtbar, sonst denken sie, das System hat sich aufgehängt.

Fazit

Durable Workflows sind nicht nur etwas für verteilte Systeme. Eine lokale App für einen einzelnen Nutzer profitiert davon auf genau die gleiche Weise: inkrementelle Arbeit, Crash-Recovery, idempotente Retries. DBOS macht die Einstiegskosten dafür extrem niedrig — dekoriere deine Funktion, lass Postgres lokal laufen, und du bekommst eine Pipeline, die das Zuklappen des Laptops, OS-Updates und dein eigenes Ctrl-C überlebt.

In Kombination mit inhaltsadressiertem Hashing ist die Ingestion nicht länger etwas, das du meidest, aus Angst, 20 Minuten warten zu müssen. Es wird zu etwas, das du einfach neu startest, wann immer du Lust dazu hast — denn ein Neustart kostet nichts, wenn sich nichts geändert hat.

Anhang: Abkürzungen in diesem Beitrag

Abbreviation	Full form	Meaning
DBOS	Database-Oriented Operating System	Eine Bibliothek, die Workflow-Schritte in Postgres sichert, sodass abgestürzte Jobs fortgesetzt statt neu gestartet werden
SHA-256	Secure Hash Algorithm, 256-bit	Ein Content-Fingerabdruck: Änderst du ein Byte einer Datei, ändert sich der Hash komplett
RAG	Retrieval-Augmented Generation	Rufe zuerst relevante Passagen aus deinen eigenen Dokumenten ab; lass das Modell daraus antworten
OCR	Optical Character Recognition	Das Umwandeln von Bildern von Text (gescannte Seiten) in maschinenlesbaren Text
FAISS	Facebook AI Similarity Search	Der Vektorindex, an den die Embeddings angehängt werden
IP (in `IndexFlatIP`)	Inner Product	FAISS’s Ähnlichkeitsmaß; entspricht der Cosinus-Ähnlichkeit bei normalisierten Vektoren
BM25	Best Match 25	Der Keyword-Index, der beim Löschen mit FAISS im Gleichschritt bleiben muss
PDF / DOCX / PPTX / XLSX / MD / CSV / TXT / HTML	Portable Document Format / Word / PowerPoint / Excel / Markdown / Comma-Separated Values / plain text / HyperText Markup Language	Die Formate, die von den entsprechenden Extraktoren verarbeitet werden
JSON	JavaScript Object Notation	Das Format der Chunk-Metadaten-Datei neben dem FAISS-Index
UTF-8	Unicode Transformation Format, 8-bit	Die Textkodierung, die beim Lesen von Klartextdateien verwendet wird
OS	Operating System	Das, was mitten in der Ingestion unter dir neu startet

Als Nächstes: — was passiert, wenn Gemma 4 enthusiastisch {"questions": [{"text": "..."},}] zurückgibt.

Teil 2 · Hybrid Retrieval in der Praxis: FAISS + BM25, verschmolzen mit RRF

Sat, 25 Apr 2026 00:00:00 +0000

Teil einer Serie über die Entwicklung von , einem vollständig lokalen KI-Lernbegleiter. Zuvor: .

Alle Abkürzungen werden im Anhang unten auf der Seite vollständig erklärt.

Die erste Version von CogniVault nutzte reines Dense Retrieval – die Suchanfrage mit embeddinggemma einbetten, in einem FAISS-Index suchen und die Top-7-Chunks an das Modell übergeben. Es funktionierte. Es funktionierte hervorragend – bis ein Nutzer ein PDF mit deutschen Gesetzestexten hochlud und nach “§3 Absatz 2” fragte.

Das Modell konnte es nicht finden.

Der Chunk war genau da. Das PDF war indiziert. Aber “§3 Absatz 2” lässt sich nicht in etwas Semantisch Sinnvolles einbetten – es ist ein Identifikator auf Token-Ebene, kein Konzept. Der dichte Vektor für die Suchanfrage landete nicht einmal in der Nähe des dichten Vektors für den Chunk, obwohl der Chunk exakt den String enthielt, nach dem der Nutzer gefragt hatte.

Dieser Bug hat reines Dense Retrieval für mich erledigt. In diesem Beitrag geht es darum, womit ich es ersetzt habe.

Zwei Arten von “ähnlich”

Du nutzt bereits jeden Tag beide Arten der Suche. Wenn Spotify ein “Song Radio” basierend auf einem Track erstellt, den du magst, vergleicht es das Gefühl – Tempo, Stimmung, Genre – und spielt dir gerne einen Song vor, dessen Titel kein einziges Wort mit dem Original gemeinsam hat. Aber wenn du Bohemian Rhapsody remastered 2011 in die Suchleiste tippst, willst du kein Gefühl. Du willst genau diesen String, und “ein ähnliches opernhaftes Rock-Epos” ist die falsche Antwort.

Suchsysteme formalisieren diese Unterscheidung in zwei Konzepte von Ähnlichkeit:

Lexikalische Ähnlichkeit – “Teilen diese Strings seltene Wörter?” Das ist es, was TF-IDF und BM25 modellieren. Sie glänzen bei Identifikatoren, Namen, Code, Fachbegriffen und direkten Zitaten.
Semantische Ähnlichkeit – “Sprechen diese Passagen über dieselbe Idee, auch wenn sie andere Wörter verwenden?” Das ist es, was Embeddings modellieren. Sie glänzen bei Paraphrasen, konzeptionellen Anfragen und natürlichsprachlichen Fragen.

Keines der beiden schließt das andere ein. Ein Nutzer, der fragt: “Wie ist die praktische Prüfung aufgebaut?”, braucht die semantische Suche – im Dokument steht nämlich nicht zwingend “Aufbau der praktischen Prüfung”. Ein Nutzer, der "§3 Absatz 2" fragt, braucht die lexikalische Suche – da gibt es kein Konzept zum Einbetten, nur einen wörtlichen String.

Production-RAG muss beides können. CogniVault macht beides und führt die Ergebnislisten dann mit Reciprocal Rank Fusion (RRF) zusammen.

Der Stack

Query
 ├── embed via embeddinggemma ──► FAISS IndexFlatIP ──► top-K dense
 └── tokenize + lowercase ──► BM25Okapi ──► top-K sparse
 │
 Reciprocal Rank Fusion ◄──┘
 │
 top-7 fused chunks

Beide Indizes liegen im Arbeitsspeicher, davor sitzt ein VectorDB-Singleton. FAISS führt eine Inner-Product-Suche über normalisierte Embeddings durch (das Skalarprodukt entspricht also dem Kosinus). BM25 ist BM25Okapi aus rank_bm25, gefüttert mit denselben Chunks, die durch einen einfachen Lowercase-und-Split-Tokenizer in Tokens zerlegt wurden.

Die Korpora werden synchron gehalten: Wenn man die Chunks einer Datei weich löscht, löst das einen BM25-Rebuild über die verbleibenden aktiven Chunks aus, und das Singleton lädt beide Indizes aus vector_store.faiss + vector_store.json (Chunk-Metadaten + Rohtext) nach jedem Ingestion-Lauf und beim App-Start neu.

Warum FAISS `IndexFlatIP` und nicht HNSW oder IVF?

IndexFlatIP ist eine exakte Brute-Force-Suche. Es scannt jeden Vektor für jede Anfrage. Bei zehntausenden Chunks ist das völlig in Ordnung – unter einer Millisekunde auf einem Laptop. CogniVault ist eine lokale Single-User-App; der Index wird nie Milliarden von Vektoren haben. Um Recall für Geschwindigkeit über HNSW oder IVF einzutauschen, würde hier nichts bringen und nur die “Exakt”-Garantie kosten. Langweilig, korrekt, schnell genug.

Wenn das Korpus so groß wird, dass Brute-Force zu zäh wird, ist der Wechsel nur eine Zeile Code. Bis dahin gewinnt der einfachste Index.

Reciprocal Rank Fusion

Der naive Weg, zwei geordnete Listen zu kombinieren, ist, sie zu scoren und zu addieren. Das klingt sinnvoll, bis du dich daran erinnerst, dass FAISS Inner-Product-Scores in einem begrenzten Bereich liefert und BM25 Scores in einem unbegrenzten – sie sind ohne Normalisierung nicht vergleichbar, und jede Normalisierung, die du wählst, ist irgendwie willkürlich.

RRF umgeht das Problem komplett. Es schaut sich nur Ränge an, keine Scores. Für jede Ergebnisliste trägt ein Item auf Rang r mit 1 / (k + r) zu seinem End-Score bei (mit k = 60 per Konvention – groß genug, um den Tail abzuflachen, klein genug, damit die Top-Items noch dominieren). Items, die in beiden Listen auftauchen, werden summiert.

# Simplified — the real implementation also de-duplicates chunks
# by (source, chunk_id, page) before scoring.
def reciprocal_rank_fusion(result_lists, k=60):
 scores = defaultdict(float)
 for results in result_lists:
 for rank, chunk_id in enumerate(results, start=1):
 scores[chunk_id] += 1.0 / (k + rank)
 return sorted(scores.items(), key=lambda kv: kv[1], reverse=True)

Das ist schon der ganze Algorithmus. Kein Tuning, keine Kalibrierung, keine Gewichte pro Korpus. Ein Chunk, der bei BM25 auf Platz 1 und bei FAISS auf Platz 4 liegt, schlägt problemlos einen Chunk, der nur in einer der Listen auf Platz 2 ist. Ein Chunk, bei dem sich beide Indizes einig sind, steigt deterministisch an die Spitze.

Das Ergebnis für die “§3 Absatz 2”-Anfrage: BM25 findet den exakten Treffer und platziert ihn auf Rang 1. FAISS findet nichts Brauchbares (seine Top-Treffer handeln allgemein von Prüfungsordnungen). RRF bringt den BM25-Treffer an die Spitze der fusionierten Liste. Problem gelöst.

Scope-Filterung mit ContextVar-Isolierung

Ein Detail, das man leicht falsch macht: Der Retriever muss sich seines Scopes bewusst sein. In CogniVault können Nutzer eine Frage auf eine einzelne Kategorie oder bestimmte Dateien beschränken. Der Scope wird durch den Request gesetzt, aber die Suche wird tief im Inneren des Strands-Agent-Loops aufgerufen, der wiederum von einem streamenden FastAPI-Handler aufgerufen wird – möglicherweise mit mehreren parallelen Requests pro Worker.

Den Scope durch jeden Funktionsaufruf durchzureichen, wäre unschön. Eine globale Variable ist unsicher. Das richtige Mittel dafür ist Pythons , das dir einen task-lokalen, isolierten State gibt, den sowohl asyncio als auch Threads respektieren.

from contextvars import ContextVar

_doc_scope: ContextVar[DocScope | None] = ContextVar("doc_scope", default=None)

def set_doc_scope(scope: DocScope | None) -> None:
 _doc_scope.set(scope)

def current_doc_scope() -> DocScope | None:
 return _doc_scope.get()

Der /rag-Request-Handler setzt den Scope ganz am Anfang jeder Streaming-Antwort; das Such-Tool liest ihn; und weil der Wert task-lokal ist, stirbt er mit dem Request. Keine globalen Variablen, kein Durchbohren von Parametern, keine Race Conditions über gleichzeitige Nutzer hinweg.

Das ist eine dieser Designentscheidungen, die nach Over-Engineering aussehen, bis du zwei Browser-Tabs offen hast und merkst, dass ohne sie der Scope-Filter von Tab A in die Frage von Tab B leaken würde.

Chunking-Entscheidungen, die sich später auszahlen

Hybrid Retrieval ist nur so gut wie seine Chunks. CogniVault nutzt einen RecursiveCharacterTextSplitter mit 1.000 Zeichen und 100 Zeichen Overlap für unstrukturierten Text – klein genug, um das Retrieval präzise zu halten, groß genug, um Kontext für das Modell zu liefern.

Für strukturierte Formate ändert sich die Strategie:

Markdown → MarkdownHeaderTextSplitter liefert einen Chunk pro H1/H2/H3-Abschnitt, wobei die Überschriftenhierarchie als Brotkrümel vorangestellt wird (“Privacy > Vault Audit > Indicators”). BM25 liebt Brotkrümel – sie lassen Anfragen mit Überschriften-Keywords sauber matchen.
CSV → Kopfzeile + 20 Zeilen pro Batch als Chunk, sodass eine Suche nach einem Spaltennamen im richtigen Block landet.
PPTX → ein Chunk pro Folie, Titel und Body-Text zusammen.
XLSX → Kopfzeile + Zeilen-Batches pro Sheet, mit einem [Sheet: name] Präfix.

Winzige Fragmente werden gefiltert: Unstrukturierter Text braucht mindestens 100 Zeichen, um ein Chunk zu werden, während die strukturierten Formate die Messlatte auf 20 senken – ein zweizeiliger Markdown-Abschnitt oder ein Sheet, das nur aus Überschriften besteht, ist zwar kurz, aber immer noch aussagekräftig. Der rekursive Splitter ist altbekanntes Terrain, aber die formatabhängigen Strategien sind viel wichtiger, als man ihnen oft zugesteht.

Was ich anders machen würde

Ein paar Dinge, die ich noch einmal überdenken würde, wenn ich noch einmal von vorn anfangen würde:

Aufhören, für BM25 mit str.split() zu tokenisieren. Es ist okay, aber ein echter Tokenizer, der mit Satzzeichen und deutschen Komposita umgehen kann, würde den Recall bei den rechtlichen Dokumenten deutlich verbessern.
Einen kleinen Reranker hinzufügen. RRF findet das richtige Set, aber ein Cross-Encoder-Rerank auf den Top 20 würde die Reihenfolge aufpolieren. Natürlich lokal gehostet – da gibt es mittlerweile gute kleine Modelle.
Query Expansion für dünne Anfragen. Zwei-Wort-Fragen wie “§3 Prüfung” könnten vor dem Retrieval über einen schnellen gemma4-Aufruf erweitert werden. Kostet Latenz, bringt aber Recall.

Nichts davon ist bisher an Bord. RRF über FAISS + BM25 ist schon so viel besser als jedes für sich allein, dass ich noch nicht den Drang gespürt habe, weiter zu optimieren.

Fazit

Wenn dein Retrieval “embed + cosine + top-k” ist, wird es genau auf dieselbe Weise scheitern wie meins – bei Anfragen, die wortwörtliche Identifikatoren enthalten, für die dein Modell kein Embedding hat. Die Lösung ist kein besseres Embedding-Modell. Es ist ein zweiter Retriever, der nicht so tut, als wäre alles ein Konzept.

FAISS für Ideen. BM25 für Strings. RRF entscheidet, wer heute Recht hat.

Anhang: Abkürzungen in diesem Beitrag

Abkürzung	Vollform	Bedeutung
RAG	Retrieval-Augmented Generation	Rufe zuerst relevante Passagen aus deinen eigenen Dokumenten ab; lass das Modell dann basierend darauf antworten
FAISS	Facebook AI Similarity Search	Metas Bibliothek zum Speichern von Vektoren und zum schnellen Finden der ähnlichsten
BM25	Best Match 25	Eine Keyword-Ranking-Formel – die 25. Ranking-Funktion, die im Informationsretrieval-System Okapi entwickelt wurde
RRF	Reciprocal Rank Fusion	Führt geordnete Listen nur anhand der Ränge zusammen: Jedes Item punktet mit `Σ 1/(k + rank)` über alle Listen hinweg
TF-IDF	Term Frequency–Inverse Document Frequency	Der Vorfahre von BM25: Bewertet Wörter danach, wie oft sie hier auftauchen vs. wie selten sie überall sonst sind
IP (in `IndexFlatIP`)	Inner Product	Das Ähnlichkeitsmaß, das FAISS berechnet; bei normalisierten Vektoren entspricht es der Kosinus-Ähnlichkeit
HNSW	Hierarchical Navigable Small World	Eine beliebte Struktur für approximative Vektor-Indizes – hier bewusst nicht verwendet
IVF	Inverted File Index	Ein weiterer approximativer FAISS-Indextyp – ebenfalls bewusst nicht verwendet
AEVO	Ausbildereignungsverordnung	Das deutsche Gesetz, dessen Anfrage “§3 Absatz 2” das reine Dense Retrieval zum Scheitern brachte
CSV / PPTX / XLSX	Comma-Separated Values / PowerPoint / Excel (Office Open XML)	Strukturierte Formate mit ihren eigenen Chunking-Strategien
H1/H2/H3	Heading levels 1–3	Die Markdown-Überschriftenebenen, die zum Aufteilen von Abschnitten verwendet werden

Als Nächstes: — wie der /rag-Endpoint von CogniVault das Denken von Gemma 4 streamt, bevor Tool-Aufrufe starten.

Teil 1 · Warum ich ein Local-First RAG gebaut habe

Mon, 20 Apr 2026 00:00:00 +0000

Alle Abkürzungen werden vollständig im Anhang am Ende der Seite erklärt.

Ich habe die letzten paar Jahre vor virtuellen Klassen voller Quereinsteiger in Deutschland verbracht und ihnen die Grundlagen des Programmierens, der Webentwicklung und Einführungskurse in KI nähergebracht. Ein Großteil der Informationen, mit denen wir zu tun haben, kann man problemlos in Cloud-basierte KI-Tools kopieren. Einiges davon aber definitiv nicht.

Prüfungsmaterialien, die der Geheimhaltung unterliegen. Das Portfolio eines Trainees mit persönlichen Details. Andere private Dokumente, die niemals das Modell von jemand anderem trainieren sollten.

Also habe ich gebaut — ein komplett lokales KI-Lern- und Produktivitäts-Tool. Keine Cloud. Keine Telemetrie. Kein “Wir könnten diese Daten verwenden, um unseren Service zu verbessern”. Einfach nur Gemma 4, das auf Ollama auf meinem Laptop läuft und mit meinen Dateien spricht.

Die undichte Abstraktion

Der Pitch für Cloud-KIs ist großartig: ein riesiges Modell, sofort verfügbar, abgerechnet nach Token. Das Kleingedruckte ist der Teil, an dem es unbequem wird:

Wo genau liegen die Daten physisch während der Inferenz?
Welcher Gerichtsbarkeit unterliegt diese Hardware heute Nachmittag?
Endet der Audit Trail an der API-Grenze, oder kannst du wirklich nachverfolgen, was mit deinen Bytes passiert ist?
Wenn du das Häkchen bei “Nicht mit meinen Daten trainieren” setzt, vertraust du dann auf ein technisches Kontrollsystem, einen Vertrag oder beides?

Für die meisten Consumer-Use-Cases kann man diese Fragen getrost wegwinken. Für Bildung, Gesundheitswesen, Finanzen, Recht, öffentliche Verwaltung ist die Antwort “Vertrau uns” einfach keine Antwort.

Was “Local-First” hier tatsächlich bedeutet

Viele Produkte nennen sich “privat”. Ich wollte drei handfeste Eigenschaften:

Das Modell lebt auf deiner Maschine. Gemma 4 (gemma4:e4b) und embeddinggemma werden via Ollama gezogen. Die Inferenz ist ein lokaler HTTP-Aufruf auf localhost.
Deine Dokumente verlassen deinen Rechner niemals. Vektoren, Chunks, Chat-Historie, Lernsessions, Achievements — alles bleibt auf der Festplatte deines Computers.
Du kannst es überprüfen. Gemma CogniVault bringt ein Privacy Audit Panel mit, das live einen “Null externe Verbindungen”-Indikator neben der Dokumentenanzahl und dem Ollama-Host anzeigt. Das ist kein Versprechen — das ist ein Statuslämpchen.

Wenn ein zukünftiger Build von Gemma CogniVault jemals einen ausgehenden Anruf nach Hause machen würde, würde dieses Panel als erstes Alarm schlagen.

Was du dafür bekommst

Auf lokal zu wechseln klingt nach einem Kompromiss — verliert man nicht die Magie der gigantischen Frontier-Modelle? In der Praxis hast du mit Gemma 4 mehr als genug:

Thinking-Modus — Die Chain-of-Thought von Gemma 4 streamt in ein ausklappbares Panel, bevor die Antwort kommt. Dem Modell beim Nachdenken über deine Dokumente zuzusehen, ist ein wirklich nützliches Lehrmittel.
Tool-Nutzung — Über das entscheidet das Modell, wann es die Knowledge Base durchsuchen, ein Dokument zusammenfassen, zwei Dateien vergleichen oder die Uhrzeit checken soll.
Vision — Hänge Bilder und PDFs direkt in den Chat an.
Generierung, die wirklich strukturiert ist — Quizzes, Multi-Lektionen-Workshops, Karteikarten-Decks und interaktive Mindmaps, die mit format="json" generiert werden, sodass der Output zuverlässig geparst werden kann.

Cognivault versucht nicht, ein riesiges Ökosystem zu sein. Es ist ein Single-Purpose-Tool, das eine Sache richtig gut macht: deine eigenen Dokumente mit einem fähigen lokalen Modell in einer privaten Umgebung nutzen. Ich muss zugeben, dass es stark von inspiriert wurde, was ich unglaublich nützlich, aber für meine Zwecke einfach nicht privat genug fand.

Der Aufbau der App

CogniVault ist in vier Bereiche unterteilt, die abbilden, wie ich tatsächlich mit Informationen auf Cloud-basierten KI-Tools arbeite:

Bereich	Wofür es da ist
Chat	Frag alles über deine Dokumente. Zitierte Antworten, Scope-Filter, Spracheingabe.
Knowledge Base	Hochladen, kategorisieren, verwalten. SHA-256 erkennt Bearbeitungen beim erneuten Upload.
Study Hub	Quiz · Workshop · Flashcards · Mindmaps — vier Wege, tiefer in die Quelle einzusteigen.
Dashboard	Gesamte Lernzeit, Streak, 25 Badges, GitHub-Style 90-Tage-Heatmap.

Alles ist über eine Sidebar erreichbar, die sich merkt, wo du aufgehört hast, auf einem Tech-Stack, der in deinen ~/Documents-Ordner passt.

Was als Nächstes kommt

Das hier ist der Start einer kurzen Serie. In den nächsten Posts werde ich genauer auf die Teile eingehen, auf die ich am stolzesten bin — und ein paar, die ich beim nächsten Mal anders bauen würde:

Hybrides Retrieval — Warum FAISS und BM25, zusammengeführt mit Reciprocal Rank Fusion
Zwei-Phasen-Streaming mit Gemma 4 und Strands Agents
Crash-resistente Ingestion mit DBOS, Hash-bewusster Re-Ingest, OCR-Fallback
Zuverlässiges JSON aus einem lokalen LLM bekommen (und was man tut, wenn es fehlschlägt)
Der Mindmap-Renderer — Was ich beim handgeschriebenen SVG gelernt habe und warum v2 React Flow nutzt
Lernen gamifizieren — 25 Badges, Idle-Gap-Sessions, 90-Tage-Heatmap
Eine lokale KI-App testen mit über 350 Tests und komplett ohne Infrastruktur

Wenn du schon mal reinschauen willst, der Code ist Open Source auf , und es gibt einen .

Deine Daten. Deine Hardware. Deine KI. Dein Vault.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
RAG	Retrieval-Augmented Generation	Relevante Passagen aus deinen Dokumenten abrufen; das Modell antwortet basierend darauf statt aus dem Trainingsgedächtnis
AI	Artificial Intelligence	Software, die Aufgaben ausführt, für die normalerweise menschliche Intelligenz erforderlich ist
LLM	Large Language Model	Ein neuronales Netz, das mit riesigen Mengen an Text trainiert wurde und Sprache lesen sowie generieren kann
HTTP	HyperText Transfer Protocol	Das Protokoll, das Browser und APIs nutzen, um Requests und Responses auszutauschen
API	Application Programming Interface	Die Grenze, an der du Software von jemand anderem aufrufst — und an der Cloud-Audit-Trails enden
IHK	Industrie- und Handelskammer	Die Institution, die in Deutschland unter anderem die Ausbildereignungsprüfung durchführt
AEVO	Ausbildereignungsverordnung	Das Prüfungsmaterial in Deutschland, das den Anstoß für dieses Projekt gab
FAISS	Facebook AI Similarity Search	Metas Vektorsuch-Bibliothek (Thema im nächsten Post)
BM25	Best Match 25	Eine klassische Keyword-Ranking-Formel (ebenfalls im nächsten Post)
SDK	Software Development Kit	Eine Sammlung von Bausteinen — hier Strands, das die Agenten-Loop bereitstellt
JSON	JavaScript Object Notation	Das universelle Textformat für strukturierte Daten
PDF	Portable Document Format	Eines der über acht Dateiformate, die CogniVault verarbeitet
SHA-256	Secure Hash Algorithm, 256-bit	Ein inhaltlicher Fingerabdruck, um bearbeitete Dateien beim erneuten Upload zu erkennen
OCR	Optical Character Recognition	Bilder von Text (Scans) in maschinenlesbaren Text verwandeln
DBOS	Database-Oriented Operating System	Die Bibliothek für durable Workflows, die hinter der crash-resistenten Ingestion steckt
SVG	Scalable Vector Graphics	Das im Browser eingebaute Format fürs Vektorzeichnen

RAG |

CogniVault Backend erklärt, Teil 1 · Das Backend kennenlernen: Drei Prozesse, vier Schichten

Die ganze App besteht aus drei Prozessen

Die vier Schichten

Ein Diagramm, alle wichtigen Teile

Der Tech-Stack und warum jedes Teil seinen Platz verdient hat

Anhang: Abkürzungen in diesem Post

Fazit

CogniVault Backend erklärt, Teil 2 · Von der Datei zum durchsuchbaren Wissen

Das Fließband

Das Kassenbuch der Fabrik: Warum die Pipeline keine Arbeit verlieren darf

Fingerabdrücke, kein Blindflug: SHA-256 Änderungserkennung

Jedes Format kriegt eine Sonderbehandlung

Chunking: 1.000 Zeichen mit 100 Zeichen Sicherheitsnetz (Überlappung)

Embedden und Speichern

Die gesamte Reise, von Anfang bis Ende

Fazit

Anhang: Abkürzungen in diesem Post

CogniVault Backend erklärt, Teil 3 · Wie aus einer Frage eine belegte Antwort wird

Zwei Bibliothekare, weil einer dich immer wieder hängen lässt

Der Agent: Ein Modell, das selbst entscheidet

Dem Modell beim Denken zusehen

Ein Speicher-Budget, kein fassloses Loch

Scope: Die KI auf bestimmte Dokumente festnageln

Fazit

Anhang: Abkürzungen in diesem Post

Teil 1 · CogniVault Architektur: Warum Standard-RAG nicht reicht (Hybride Suche)

Zwei Wege, ein Buch zu finden

Der Agent entscheidet, wann gesucht wird

Was kommt als Nächstes?

Anhang: Abkürzungen in diesem Beitrag

Gemma CogniVault

Überblick

Was drinsteckt

Vier Bereiche

Highlights

Darüber schreiben

Probier es aus

Teil 4 · Crash-Resumable Ingestion: DBOS, SHA-256 und wie man ein kill -9 überlebt

Die Pipeline

SHA-256 als einzige Quelle der Wahrheit

DBOS-Workflows

Die Format-Extraktoren

Soft Delete, nicht Hard Delete

Was der User sieht

Fallstricke und Randfälle

Fazit

Anhang: Abkürzungen in diesem Beitrag

Teil 2 · Hybrid Retrieval in der Praxis: FAISS + BM25, verschmolzen mit RRF

Zwei Arten von “ähnlich”

Der Stack

Warum FAISS IndexFlatIP und nicht HNSW oder IVF?

Reciprocal Rank Fusion

Scope-Filterung mit ContextVar-Isolierung

Chunking-Entscheidungen, die sich später auszahlen

Was ich anders machen würde

Fazit

Anhang: Abkürzungen in diesem Beitrag

Teil 1 · Warum ich ein Local-First RAG gebaut habe

Die undichte Abstraktion

Was “Local-First” hier tatsächlich bedeutet

Was du dafür bekommst

Der Aufbau der App

Was als Nächstes kommt

Anhang: Abkürzungen in diesem Post

Warum FAISS `IndexFlatIP` und nicht HNSW oder IVF?