Me |

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.

CogniVault Backend erklärt, Teil 4 · Study Tools, Fortschritt und die Privacy-Belege

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

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

In haben wir eine Frage durch das hybride Retrieval und den Agenten-Loop bis hin zur zitierten Antwort verfolgt. In diesem letzten Teil wird dieselbe Maschinerie auf ein ganz anderes Ziel ausgerichtet: Dir etwas beizubringen — und dann schließen wir die Serie ab, indem wir das zentrale Versprechen des Projekts überprüfen: Nichts verlässt deinen Rechner.

Ein Rezept, vier Lerntools

CogniVault generiert Quizzes, mehrteilige Workshops, Karteikartendecks und Mindmaps aus deinen Dokumenten. Vier verschiedene Outputs — aber unter der Haube steckt ein gemeinsames Fünf-Schritte-Rezept:

Abrufen (Retrieve). Dieselbe hybride Suche wie aus Teil 3, aber statt deiner Frage lautet der Such-Prompt etwas Breitgefächertes wie “Schlüsselkonzepte, Definitionen, wichtige Fakten, Hauptideen”, eingeschränkt auf die von dir ausgewählten Dokumente. Bis zu 15 repräsentative Chunks kommen zurück.
Mit einem Template prompten. Die Anweisungen an Gemma sind nicht tief in Python vergraben — es sind editierbare Markdown-Dateien im Ordner backend/prompts/ (quiz.md, flashcards.md usw.). Legst du eine modifizierte Kopie in backend/prompts/custom/ ab, überschreibt sie die mitgelieferte Version beim allerersten Request danach. Kein Neustart, keine Code-Änderung. Prompt Engineering als reine Konfiguration.
Output erzwingen (Constrain). Ein kleines lokales Modell zu bitten, “bitte gib JSON zurück”, klappt in den meisten Fällen — und in den meisten Fällen bedeutet in Produktion schlichtweg einen Bug. CogniVault nutzt Ollamas grammatikgebundene Generierung (format="json"), was ungültiges JSON nicht nur unwahrscheinlich, sondern unmöglich macht, gepaart mit einer niedrigen Temperature für Konstanz. Die ganze Geschichte, wie man zuverlässige Strukturen aus einem 4-Milliarden-Parameter-Modell presst, findest du in .
Defensiv validieren. Jedes generierte Item wird Feld für Feld gecheckt. Fehlerhafte Items werden verworfen, statt den kompletten Batch crashen zu lassen. Kleine Modelle verhauen manchmal eine von zehn Fragen; ein Produkt sollte deswegen nicht gleich zusammenbrechen.
Persistieren. Alles landet in SQLite. Quizzes sind später fortsetzbar, Workshop-Fortschritte überleben Neustarts und der Status von Karteikarten wird pro Deck gespeichert.

Hier ist das Rezept für ein Quiz in Aktion:

%%{init: {'sequence': {'actorFontSize': 28, 'messageFontSize': 24, 'loopTextFontSize': 22, 'noteFontSize': 22}}}%% sequenceDiagram actor U as Du participant F as Study Hub UI participant B as FastAPI participant V as VectorDB participant O as Ollama (gemma4:e4b) participant S as SQLite U->>F: Scope, Schwierigkeit, Fragenanzahl wählen F->>B: POST /api/study/quiz/generate B->>V: Hybride Suche, eingeschränkt auf deine Dokumente V-->>B: Bis zu 15 repräsentative Chunks B->>B: Render das quiz.md Prompt-Template B->>O: chat(format="json", niedrige Temperature) O-->>B: Grammatikgebundenes JSON B->>B: Jede Frage validieren, schlechte verwerfen B->>S: Quiz speichern (später fortsetzbar) B-->>F: Typisierte Antwort F-->>U: Spielen, einreichen, punkten — und vielleicht ein neues Badge

Die vier Tools unterscheiden sich nur in ihrem Template und ihrer Form: Quizzes produzieren Multiple-Choice- und Wahr/Falsch-Fragen mit Erklärungen; Workshops erstellen zuerst eine Gliederung und schreiben dann jede Lektion on demand, wenn du sie öffnest; Karteikarten liefern Vorder-/Rückseiten-Paare; Mindmaps generieren einen Themenbaum, den das Frontend als interaktives Diagramm rendert. (Dieser Renderer war übrigens sein eigenes kleines Abenteuer: .)

Sessions, die sich selbst tracken

Die meisten Lern-Apps zwingen dich, einen Start-Button zu drücken, und die meisten Leute vergessen es. CogniVault geht da einen anderen Weg: Lernsessions werden abgeleitet, nicht manuell gestartet.

Jede Chatnachricht verlängert entweder die aktuelle Session oder — nach einer 15-minütigen Pause — startet stillschweigend eine neue. Geh einen Kaffee holen, komm zurück, mach weiter: gleiche Session. Komm morgen wieder: neue Session. Keine Buttons, kein Vergessen.

Jede Nachricht speichert außerdem ein winziges Event (Zeitstempel, ob du einen Scope-Filter oder Dateianhänge genutzt hast) in progress.db — eine SQLite-Datenbank, also eine komplette relationale Datenbank in einer einzigen Datei. Elf Tabellen halten alles fest: Sessions, Nachrichten-Events, verdiente Badges, Quiz-Versuche und gespeicherte Quizzes, Workshops und Lektionen, Decks und Karten sowie Mindmaps.

Eine kleine Engineering-Note, die sich abzugucken lohnt: Der Tracking-Call im Chat-Endpoint ist so verpackt, dass er den Chat niemals blockieren oder abbrechen kann. Analytics müssen immer Beifahrer sein, niemals der Fahrer.

25 Badges, als Daten definiert

Die Achievements sind nicht als if-Statements im Code verstreut. Sie leben in einer einzigen JSON-Datei — 25 Einträge, jeder mit Code, Name, Icon, der Metrik, die er überwacht, und einem Zielwert. Nach jeder relevanten Aktion prüft ein Evaluator jede Definition gegen die Datenbank und speichert neu verdiente Badges. Einige Badges bilden Leitern und verweisen auf das nächste Level.

Deklarativ schlägt hier imperativ aus einem einfachen Grund: Badge Nummer 26 hinzuzufügen bedeutet einen JSON-Eintrag zu ergänzen, nicht neue Logik zu schreiben. Das Design hinter den Streaks (Serien), der Pausen-Regel und der 90-Tage-Heatmap hat einen eigenen Artikel bekommen: .

Spracheingabe, ganz ohne Cloud-Mikrofon

Der Mikrofon-Button wird von faster-whisper befeuert — OpenAIs Whisper Spracherkennungsmodell, neu implementiert auf einer schnelleren Inference-Engine. Es läuft auf deiner CPU mit int8-Quantisierung (8-Bit-Zahlen statt 32-Bit: kleiner, schneller, genau genug). Kein Ton verlässt jemals deinen Rechner.

Das Modell wird erst bei der ersten Transkription geladen (Lazy Loading), damit die App sofort startet. Und wenn faster-whisper gar nicht erst installiert ist, versteckt das Frontend den Mikrofon-Button einfach. Features sollten sanft degradieren, nicht explodieren.

Die Privacy-Belege

Die Serie begann mit einem Versprechen: Nichts verlässt deinen Rechner. Versprechen sind billig — hier ist das Audit. Jedes Byte, das CogniVault speichert, und wo genau es lebt:

Daten	Speicherort	Format
Deine hochgeladenen Dateien	Ordner `docs/`	Die Originaldateien
Suchvektoren	`vector_store.faiss`	FAISS Binär-Index
Chunk-Text und Metadaten	`vector_store.json`	JSON
Datei-zu-Kategorie-Zuweisung	`categories.json`	JSON
Chat-Sessions	`chat_history.json`	JSON
Sessions, Badges, Quizzes, Workshops, Decks, Mindmaps	`progress.db`	SQLite
Ingestion Checkpoints	PostgreSQL (lokales Docker-Volume)	DBOS Systemtabellen
Die KI-Modelle selbst	Ollamas lokaler Model-Store	Modell-Gewichte

Nichts aus dieser Tabelle liegt auf dem Computer von jemand anderem. Inference geht an localhost. Embeddings gehen an localhost. Der einzige ausgehende Request, den das Backend jemals macht, ist der URL-Import — und das nur auf deinen ausdrücklichen Wunsch und geschützt davor, private Adressen abzurufen. Die App zeigt diese Statistiken sogar live im “Privacy Vault Audit”-Panel an.

Und weil Vertrauen mehr braucht als nur eine Tabelle: Das gesamte Backend ist von einer pytest-Suite abgedeckt, die du selbst ausführen kannst. Der Ansatz dazu ist in dokumentiert.

Fazit der Serie

Vier Teile, eine Architektur:

— Drei Prozesse, vier Schichten und ein Decoder-Ring für den Jargon
— Eine dauerhafte, formatbewusste Pipeline, die jedes Dokument in durchsuchbare Vektoren verwandelt
— Zwei Retriever, die gegenseitig ihre blinden Flecken abdecken, durch Rang fusioniert und von einem Agenten gesteuert werden
Teil 4 — Dieselbe Maschinerie, die Lernmaterialien generiert, Fortschritt ohne Buttons trackt, und eine Speichermap ohne Cloud-Abhängigkeiten

Wenn es ein Hauptthema gibt, dann das: Langweilige, verifizierbare Entscheidungen im Dienste der Privatsphäre. Exakte Suche statt Approximation. SQLite-Dateien statt gehosteter Datenbanken. Grammatikgebundenes JSON statt hoffnungsvollem Parsen. Soft-Deletes statt cleverer Index-Eingriffe. Jedes Puzzleteil ist etwas, das du öffnen, lesen und überprüfen kannst — und genau das ist der Punkt.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
JSON	JavaScript Object Notation	Das strukturierte Format, das die Generatoren vom Modell erzwingen
SQLite / SQL	(SQL = Structured Query Language)	Eine komplette relationale Datenbank, die in einer einzigen Datei lebt (`progress.db`)
MCQ	Multiple-Choice Question	Einer der beiden Quiz-Fragentypen (der andere ist Wahr/Falsch)
CPU	Central Processing Unit	Hier läuft Whisper — keine Grafikkarte notwendig
int8	8-bit integer (Quantisierung)	Modellgewichte als kleine Integer speichern: kleiner, schneller, genau genug
KI	Künstliche Intelligenz (AI)	Software, die Aufgaben ausführt, die normalerweise menschliche Intelligenz erfordern
API	Application Programming Interface	Die Endpunkte, die der Study Hub und das Dashboard aufrufen
FAISS	Facebook AI Similarity Search	Der Vektor-Index in der Privacy-Tabelle
DBOS	Database-Oriented Operating System	Die Durable-Workflow-Bibliothek, deren Checkpoints in PostgreSQL leben
SSRF	Server-Side Request Forgery	Die Art von Angriff, vor dem der URL-Importer schützt
PNG / PDF	Portable Network Graphics / Portable Document Format	Zwei der Export-Formate für Mindmaps (neben Markdown)
SVG	Scalable Vector Graphics	Das Zeichenformat im Browser, das hinter dem interaktiven Mindmap-Rendering steckt

Nächste Schritte: Klone und lies mit — die README skizziert die komplette Architektur, und jede Behauptung in dieser Serie kann direkt mit dem Code unter backend/ abgeglichen werden. Und falls du Lust auf die Deep-Dive-Versionen dieser Themen hast: Die knüpft genau da an, wo dieser Rundgang endet.

Teil 3 · CogniVault Architektur: Warum wir Ollama nicht in Docker packen

Wed, 03 Jun 2026 00:00:00 +0000

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

Die goldene Regel für modernes Software-Deployment heißt Containerisierung. Pack alles in Docker, um die Abhängigkeiten zu isolieren, und es läuft auf jeder Maschine absolut identisch.

Als ich CogniVault anfangs entworfen habe, war der erste Impuls, den FastAPI-Server, die PostgreSQL-Datenbank und die Ollama LLM-Engine in ein einziges, sicheres Docker-Netzwerk zu stecken.

Aber das haben wir nicht getan. Wir haben Ollama nativ auf dem Host-System laufen lassen. Schauen wir uns mal an, warum.

Das GPU-Passthrough-Problem

Stell dir deine GPU wie die Küche in einem Restaurant vor. Die Köche (deine KI-Modelle) müssen in der Küche sein — am Herd stehen, die Hände an den Geräten. Stell dir nun vor, du sagst den Köchen, sie müssten aus einem verschlossenen Konferenzraum am Ende des Flurs kochen und Anweisungen durch eine Durchreiche rufen. Technisch gesehen kommt vielleicht immer noch Essen heraus. Aber es wird nicht schnell gehen.

Dieser verschlossene Raum ist ein Container. Large Language Models wie Gemma 4 brauchen direkten, ungehinderten Zugriff auf die GPU deiner Hardware (wie Apple Silicons Unified Memory oder eine dedizierte Nvidia-Karte), um Text schnell genug für ein Echtzeit-Chat-Interface zu generieren. Und die Situation ist je nach Plattform unterschiedlich:

Auf macOS lässt Docker Container in einer ressourcenschonenden virtuellen Maschine laufen — und es gibt aktuell überhaupt kein GPU (Metal) Passthrough. Ein Ollama-Container auf einem Mac läuft also nur über die CPU. Für eine Chat-App ist das an sich schon ein K.o.-Kriterium.
Unter Linux gibt es Nvidia GPU-Passthrough und es funktioniert auch, aber es erfordert zusätzliche Toolkit-Konfiguration, die die “es funktioniert einfach”-Philosophie der lokalen Entwicklung zunichte macht.

Wenn man Ollama nativ laufen lässt, umgeht man diese ganze Kategorie von Problemen.

Die Brückenlösung

CogniVault verwendet ein geteiltes Deployment-Modell, das die Anwendungslogik von der rechenintensiven KI-Verarbeitung trennt.

Die sicheren Räume (Docker): PostgreSQL — wo das DBOS-Workflow-Ledger aus liegt — befindet sich in einem Docker Bridge Network (einem privaten virtuellen Netzwerk). Isoliert, sauber, reproduzierbar.
Das Hauptgebäude (Nativer Host): Ollama läuft direkt auf deinem Mac-, Windows- oder Linux-Betriebssystem und hat so direkten Zugriff auf deine GPU.

CogniVault wird tatsächlich mit zwei Ausführungsmodi ausgeliefert, und es lohnt sich, hier genau zu sein:

Der Standardmodus (scripts/start.sh): Nur PostgreSQL läuft in Docker. Das FastAPI-Backend läuft ebenfalls nativ (python -m backend.main), direkt neben Ollama. Das ist der einfachste Loop für die lokale Entwicklung.
Der vollcontainerisierte Modus (docker-compose.yaml): Die FastAPI-App gesellt sich zu Postgres ins Compose-Netzwerk. In diesem Modus erreicht der App-Container die native Ollama-Engine über eine spezielle Docker-Routing-Adresse: host.docker.internal:11434.

So oder so bleibt die Regel die gleiche: Das Modell kommt niemals in die Box.

graph TD Client[📱 Browser / Nutzer] -->|HTTP: 8000| App subgraph HostMachine ["Host-OS: Nativer GPU-Zugriff"] Ollama[🧠 Ollama Engine] Models[(gemma4:e4b)] Ollama <--> Models subgraph DockerNetzwerk ["Docker Compose Netzwerk"] App[🖥️ FastAPI App Container] Postgres[(🐘 PostgreSQL)] App <-->|Interner Port 5432| Postgres end App <-->|host.docker.internal:11434| Ollama end

Was ist mit der Vektor-Datenbank?

Dir fällt vielleicht auf, dass FAISS hier kein Container ist. Im Gegensatz zu massiven SQL-Datenbanken ist FAISS extrem leichtgewichtig. In CogniVault läuft FAISS direkt im Speicher des FastAPI-Python-Prozesses und speichert seine Daten in einem lokalen Ordner. Es braucht keinen eigenen Container.

Indem wir die schwere LLM-Arbeit direkt auf der Hardware (Bare-Metal) erledigen und die Buchhaltung in Containern belassen, erreichen wir genau die Balance, an der die lokale KI-Entwicklung so oft scheitert: null Abhängigkeitskonflikte kombiniert mit maximaler KI-Performance.

Erlebe es in Aktion

Das schließt unsere CogniVault-Architekturserie ab! Wenn du diesen zu 100% lokalen, datenschutzfreundlichen Lernbegleiter auf deiner eigenen Hardware ausführen möchtest:

Hol dir den Code:
Schau dir das Walkthrough an:

Anhang: Abkürzungen in diesem Beitrag

Abbreviation	Full form	Meaning
GPU	Graphics Processing Unit	Die Hardware, die lokale Modell-Inferenz schnell macht; Container haben Probleme, darauf zuzugreifen
LLM	Large Language Model	Ein auf riesigen Textmengen trainiertes neuronales Netzwerk, das Sprache lesen und erzeugen kann
AI	Artificial Intelligence	Software, die Aufgaben ausführt, für die normalerweise menschliche Intelligenz erforderlich ist
API	Application Programming Interface	Die URLs, die das Frontend aufruft, um mit dem Backend zu kommunizieren
HTTP	HyperText Transfer Protocol	Das Protokoll, mit dem Browser und APIs Anfragen und Antworten austauschen
OS	Operating System	macOS, Windows oder Linux — wo Ollama nativ läuft
DBOS	Database-Oriented Operating System	Die Durable-Workflow-Bibliothek, deren Ledger im Postgres-Container liegt (siehe Teil 2)
SQL	Structured Query Language	Die Sprache relationaler Datenbanken wie PostgreSQL
FAISS	Facebook AI Similarity Search	Der In-Process-Vektorindex — absichtlich kein separater Container
VM	Virtual Machine	Die versteckte Schicht, die Docker auf macOS nutzt — und der Grund, warum Mac-Container die GPU nicht erreichen können

Teil 2 · CogniVault Architektur: Dauerhafte Ingestion mit DBOS

Tue, 02 Jun 2026 00:00:00 +0000

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

In einem einfachen lokalen KI-Setup ist das Hinzufügen von Dokumenten zu deiner Datenbank normalerweise nur ein simples Python-Skript. Du öffnest ein PDF, zerhackst den Text in Chunks, verwandelst diese Chunks in Mathe (Embeddings) und speicherst sie.

Das funktioniert super für ein fünfseitiges Essay. Aber was passiert, wenn du ein 1.000-seitiges technisches Handbuch einliest (Ingestion) und dein Laptop bei Seite 800 in den Ruhemodus geht?

Das Skript stirbt. Wenn du deinen Laptop aufweckst, musst du wieder bei Seite 1 anfangen und verschwendest so Zeit und Rechenleistung. Ein einfaches Skript reichte für CogniVault nicht aus. Wir brauchten einen Durable Workflow (dauerhaften Workflow).

Das Fabrikbuch (DBOS)

Stell dir die Daten-Ingestion wie ein Fließband in einer Fabrik vor. Wenn der Strom ausfällt, sollten die Arbeiter nicht jedes Produkt von Grund auf neu bauen müssen. Sie sollten einfach in ein permanentes Kassenbuch (Ledger) schauen, genau sehen, welche Kiste sie gerade gepackt haben, als das Licht ausging, und dort weitermachen.

CogniVault verwendet ein Framework namens DBOS (Database-Oriented Operating System), das von einer PostgreSQL-Datenbank gestützt wird, um als dieses Buch zu fungieren.

Jeder Schritt des Ingestion-Prozesses protokolliert seinen Abschluss in Postgres. Wenn der Server mittendrin abstürzt, passiert im Moment nichts Dramatisches — die Magie entfaltet sich beim Neustart: DBOS liest das Buch, sieht, welche Schritte bereits abgeschlossen sind, spielt die aufgezeichneten Ergebnisse sofort ab und macht beim ersten unvollendeten Schritt weiter.

Eine wichtige Grenze: Postgres enthält nur das Buch — welche Schritte gelaufen sind und was sie zurückgegeben haben. Deine Dokumente, Chunks und Vektoren leben dort nie. Sie wandern in einen FAISS-Index plus eine JSON-Metadaten-Datei auf der Festplatte.

SHA-256 Hashing: Der Idempotenz-Trick

Das System muss auch bei erneuten Uploads clever sein. Wenn du einen Tippfehler in einem riesigen Dokument behebst und es noch einmal hochlädst, willst du nicht, dass das System 10 Minuten verschwendet, um das Ganze neu einzubetten (re-embedding).

CogniVault erreicht Idempotenz (die Fähigkeit, dieselbe Operation mehrmals auszuführen, ohne das Ergebnis nach der ersten Anwendung zu verändern) mit dem allerersten Schritt des Workflows: Es scannt den docs/-Ordner und generiert einen SHA-256-Hash (einen einzigartigen digitalen Fingerabdruck) für jede Datei.

Wenn der Hash neu ist, wird die Datei verarbeitet.
Wenn sich der Hash geändert hat (weil du die Datei bearbeitet hast), löscht es die alten Text-Chunks per “Soft-Delete” und bettet nur die neue Version neu ein.
Wenn der Hash identisch ist, überspringt es die Datei komplett.

Hier können wir sehen, wie das logisch abläuft:

graph TD Raw[📄 Hochgeladenes Dokument] --> DBOS[🐘 DBOS Workflow startet] subgraph DauerhaftePipeline ["Dauerhafte Ingestion-Pipeline"] DBOS -->|Schritt 1| Hash{Hash-Prüfung SHA-256} Hash -->|Unverändert| Skip[Verarbeitung überspringen] Hash -->|Neu / Geändert| Extract[✂️ Schritt 2: Text pro Dokument extrahieren] Extract --> Chunk[Chunking: 1000 Zeichen, 100 Überlappung] Chunk -->|Schritt 3, 5er-Batches| Embed[🔢 embeddinggemma Embeddings] Embed -->|Schritt 4| Save[(💾 FAISS Index + Metadaten JSON)] end Save -->|Workflow abgeschlossen| Done[✅ Bereit für die Suche]

(Ein Detail für die Neugierigen: Die per Checkpoint gesicherten Schritte sind der Scan, die Extraktion pro Dokument, jeder Embedding-Batch und das Speichern. Das Chunking dazwischen ist schnelle, reine Python-Arbeit, also läuft es einfach als Teil des Workflow-Körpers erneut — es mit einem Checkpoint zu versehen, würde mehr kosten, als es neu zu machen.)

Was kommt als Nächstes?

Indem wir die Ingestion-Pipeline in DBOS verpacken, verwandelt sich das System von einem anfälligen Skript in eine robuste Zustandsmaschine (State Machine) auf Produktionsniveau.

Jetzt, da unsere Daten sicher eingelesen sind, wie deployen wir diese gesamte Pipeline, ohne die GPU unseres Laptops zum Schmelzen zu bringen? Lies Teil 3: Warum wir Ollama nicht in Docker packen

Du kannst die DBOS-Implementierung auch direkt in der Datei backend/services/ingest.py im erkunden.

Anhang: Abkürzungen in diesem Beitrag

Abbreviation	Full form	Meaning
DBOS	Database-Oriented Operating System	Eine Bibliothek, die Workflow-Schritte in einer Datenbank sichert, sodass abgestürzte Jobs fortgesetzt statt neu gestartet werden
SHA-256	Secure Hash Algorithm, 256-bit	Eine Fingerabdruck-Funktion: Jede Datei wird auf einen einzigartigen 64-Zeichen-Hash abgebildet; änderst du ein Byte, ändert sich der Hash komplett
PDF	Portable Document Format	Das Dokumentenformat, dessen Text (und Scans) die Pipeline extrahiert
FAISS	Facebook AI Similarity Search	Metas Vektorsuch-Bibliothek — wo die Embeddings tatsächlich leben
JSON	JavaScript Object Notation	Das Textformat, das für die Chunk-Metadaten-Datei neben dem FAISS-Index verwendet wird
AI	Artificial Intelligence	Software, die Aufgaben ausführt, für die normalerweise menschliche Intelligenz erforderlich ist
GPU	Graphics Processing Unit	Die Hardware, die lokale Modell-Inferenz schnell macht — das Thema von Teil 3

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 8 · Eine lokale KI-App testen: 351 Tests, Null Infrastruktur

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

Teil einer Serie über den Aufbau von . Zuvor: . Alle Abkürzungen werden vollständig im Anhang am Ende der Seite erklärt.

CogniVault hat 351 Tests verteilt auf 22 Dateien (zum Zeitpunkt des Schreibens — die Suite wächst mit der App). Keiner davon benötigt Ollama. Keiner benötigt Postgres. Keiner braucht ein echtes PDF, ein Mikrofon oder eine Internetverbindung. Die gesamte Suite läuft in etwa drei Sekunden auf meinem Laptop.

Das liegt nicht daran, dass es nicht viel zu testen gäbe — die Oberfläche ist groß. Es liegt daran, dass die Test-Suite um ein einziges Prinzip herum aufgebaut ist: An den Rändern mocken, überall sonst echt. In diesem Post geht es darum, was “der Rand” in einer lokalen KI-App bedeutet und wie man die Grenze so zieht, dass die Suite nützlich bleibt anstatt nur dekorativ zu sein.

Die 22 Testdateien

Datei	Was sie abdeckt
`test_api.py`	Die HTTP-Endpoints (Upload, Ingest, RAG, Historie, KB-Browsing)
`test_tools.py`	Taschenrechner, Uhr, KB-Such-Tool
`test_thinking.py`	Zwei-Phasen-Stream, Thinking-Tokens, Session-Isolation
`test_chat_attachments.py`	Multi-File-Attach, PDF/DOCX-Extraktion, Größenlimits
`test_chat_memory.py`	Budget für Session-Historie, Trimming, Restart-Rebuild
`test_doc_scope_filter.py`	ContextVar-Isolation pro Request, Suchfilterung
`test_doc_tools.py`	`list_documents`, `analyze_document`, `compare_documents`
`test_edit_regenerate.py`	Historie zurückspulen, trim_history_to_turns-Validierung
`test_structure_chunking.py`	Markdown-Header-Splits, CSV-Zeilen-Batches, Dokumenttypen
`test_ocr_fallback.py`	OCR-Trigger-Schwellenwert, Graceful Degradation
`test_new_formats.py`	PPTX-, XLSX-, HTML-Extraktoren, Extension-Routing
`test_docx_url.py`	DOCX-Ingestion und URL-Import (mit dem SSRF-Schutz)
`test_reingest.py`	SHA-256-Änderungserkennung, Idempotenz
`test_vector_db.py`	BM25, FAISS, RRF-Fusion, Hybrid-Suche
`test_audio.py`	Whisper-Transkriptions-Endpoint
`test_progress.py`	Sessions, tägliche Aggregation, Achievement-Kriterien
`test_prompts.py`	Der Prompt-Template-Loader und benutzerdefinierte Overrides
`test_vault_stats.py`	Die Privacy Vault Audit-Zahlen
`test_quiz.py` / `test_workshop.py` / `test_flashcards.py` / `test_mindmaps.py`	Parsing pro Modus, Endpoints, Achievements

Alles, was isoliert getestet werden kann, wird isoliert getestet. Alles, was durch die FastAPI-Schicht getestet werden muss, wird dort getestet, aber die einzigen gemockten Dinge sind die Aufrufe, die die Prozessgrenze überschreiten.

Was gemockt wird, was nicht

Die mit Abstand wichtigste Frage in so einem Projekt: Wo setzt man den Stub an?

[ React frontend ] ←─ nicht im Scope für Backend-Tests
 │
 ▼
[ FastAPI handlers ] ←─ direkt mit TestClient getestet
 │
 ▼
[ services/ ] ←─ direkt getestet (vector_db, rag_agent, generators)
 │
 ├─► [ FAISS + BM25 ] ←─ echt, in-memory, schnell
 ├─► [ SQLite ] ←─ echt, gegen eine tmp_path-Datei
 ├─► [ DBOS ] ←─ gepatched (kein Start, kein Postgres)
 ├─► [ Ollama ] ←─ gepatched am Import-Ort jedes Services
 └─► [ Whisper ] ←─ als Stub (kein 145-MB-Modell-Laden)

Als Faustregel gilt: Alles, was eine Prozess- oder Netzwerkgrenze überschreitet, wird gemockt. Alles In-Process läuft echt.

FAISS und BM25 sind echt, weil es Bibliotheken sind, die wir in den Testprozess einbinden. SQLite ist echt, weil es eine Datei ist. DBOS ist gepatched, weil beim Starten eine Postgres-Verbindung erwartet wird, und das ist Netzwerk. Ollama ist gepatched, weil es HTTP ist. Whisper ist als Stub ausgeführt, weil das Laden eines 145 MB großen Modells in einem Unit-Test ziemlich albern ist.

Dieses Prinzip hält die Test-Suite schnell (kein I/O, den das OS nicht in Millisekunden verarbeiten kann) und aussagekräftig (die echten Code-Pfade durch Retrieval, Chunking, Parsing und Scope-Filterung werden ausgeführt).

Ollama mocken

Die meisten CogniVault-Tests brauchen irgendeinen Modell-Output, aber es ist ihnen egal, welches Modell ihn produziert hat. Jeder Service importiert das ollama-Modul direkt, daher patchen die Tests diese Referenz direkt am Import-Ort des Services:

# Real pattern from test_quiz.py
from unittest.mock import patch
from backend.services import quiz_generator

def test_quiz_parses_questions():
 fake = {"message": {"content": json.dumps({"questions": [VALID_MCQ] * 5})}}
 with patch.object(quiz_generator, "ollama") as mock_ollama:
 mock_ollama.chat.return_value = fake
 result = quiz_generator.generate_quiz(
 difficulty="beginner", num_questions=5, question_types=["mcq"],
 )
 assert len(result.questions) == 5

Eine Streaming-Variante füttert Chunk-Sequenzen anstelle einer einzelnen Antwort; dies wird für die RAG- und Thinking-Tests verwendet. Die wichtigste Eigenschaft: Ein patch.object auf das Modul, das der Service tatsächlich benutzt. Keine tiefen Mock-Hierarchien, keine fragilen String-Pfade in Third-Party-Interna. Leicht in einem Code-Review zu lesen, leicht zu debuggen, wenn ein Test fehlschlägt.

DBOS mocken

DBOS erwartet, dass sich launch() mit Postgres verbindet. Die gemeinsam genutzte client-Fixture in der conftest.py patcht einfach die dbos-Instanz, bevor die App ausgeführt wird:

# Real pattern from conftest.py
@pytest.fixture()
def client():
 """A FastAPI TestClient with DBOS launch mocked out — no Postgres needed."""
 with patch("backend.services.ingest.dbos") as mock_dbos:
 mock_dbos.launch = MagicMock()
 from backend.main import app
 with TestClient(app) as c:
 yield c

Die dekorierten Workflow-Schritte werden weiterhin als gewöhnliche Python-Funktionen ausgeführt — wir verlieren die Durability-Semantik, aber die Tests prüfen ja nicht Durability, sondern die Geschäftslogik innerhalb der Schritte (Hash-Erkennung, Extraktion, Chunking). Die Durability-Schicht hat ihre eigenen Tests weiter oben, in der eigenen Suite von DBOS.

Es gibt noch eine zweite Isolationsschicht, die jeden Test automatisch durchläuft: Eine Autouse-Fixture richtet den Docs-Ordner, den FAISS-Index und die Metadaten-Datei über Umgebungsvariablen auf einen tmp_path pro Test ein, sodass kein Test jemals echte Daten auf der Festplatte berühren kann.

Echtes SQLite, mit einem Override

Progress-Tracking, Achievements, Quiz-Speicherung, Deck-CRUD — alles SQLite. Der Progress-Tracker bietet eine einzige Test-Nahtstelle: Einen Pfad-Override auf Modulebene.

# Real pattern from test_quiz.py
@pytest.fixture(autouse=True)
def _isolate_progress_db(tmp_path, monkeypatch):
 monkeypatch.setattr(progress_tracker, "_db_path_override",
 str(tmp_path / "progress_test.db"))

Jeder Test bekommt eine frische Datenbankdatei; das Schema wird bei der ersten Nutzung automatisch erstellt. Kein Drama mit Connection-Pooling, kein durchgesickerter Status zwischen Tests, keine in-memory :memory:-Gymnastik. Einfach eine Temp-Datei pro Test.

Das ist die Art von Test, die Fehler aufdeckt, die ein Mock auf SQL-Ebene niemals sehen würde — ein fehlender Index, eine vermurkste Migration, ein Constraint, der nicht auslöst. SQLite ist auf jedem Rechner, den ich je besessen habe, so schnell, dass “die echte Datenbank nutzen” nicht mal ein Kompromiss ist.

Das TestClient-Pattern

Für HTTP-Tests führt FastAPIs TestClient die App in-process aus. Der Upload, die Validierung, das Chunking, das Vector-Store-Update, die Response-Serialisierung — jede Schicht läuft echt. Nur die Aufrufe, die den Prozess verlassen würden (der Ollama-Embedding-Aufruf in der Ingestion, der Modell-Aufruf in der Generierung), sind gepatched. Das ist genau die richtige Grenze: Der Test verifiziert die Integration dieser Schichten, hängt aber nicht von einem externen Service ab.

Die Streaming-Endpoint-Tests nutzen einen leicht anderen Stil — sie iterieren über den Response-Body und parsen jede NDJSON-Zeile (ein JSON-Envelope pro Zeile, wie im beschrieben) — aber das Prinzip ist identisch.

Lücken in der Abdeckung, die ich akzeptiere

Drei Dinge, die die Test-Suite nicht abdeckt:

Das Frontend. Keine React-Tests in dieser Suite — das ist ein separates Anliegen. Die meisten Fehler zeigen sich ohnehin in API-Tests, da das Frontend ein Thin-Client über einer typisierten API ist.
Die tatsächliche Ollama-Prompt-Qualität. Ob gemma4:e4b wirklich nützliche Quizfragen generiert, ist nichts, was Tests beantworten können. Das ist Evaluierung, kein Testing. Es gehört in eine separate Testumgebung, in der ein echtes Modell läuft.
Race Conditions über DBOS-Workflow-Restarts hinweg. Der Resume-Pfad wird auf Logikebene geprüft, aber der volle Zustandsraum von “Was passiert, wenn Postgres in genau diesem Moment weg ist” ist zu groß, um ihn komplett durchzuspielen.

Das sind bewusste Lücken. Die Test-Suite ist dazu da, Regressionen in meinem Code zu fangen; sie ist kein Ersatz für Evaluierung, Integrationstests oder gar echtes Chaos-Engineering.

Wofür die Suite eigentlich da ist

Zwei Dinge, in dieser Reihenfolge:

Vertrauen beim Refactoring. Wenn ich die Agent-Loop rausreiße und eine neue einsetze, laufen die Tests dann immer noch grün durch? Wenn ja, haben sich die API-Verträge, die mir wichtig sind, nicht verschoben.
Absicherung für PR-Reviews. Jeder PR lässt die Suite in der CI laufen. Ein grüner Durchlauf ist Voraussetzung für den Merge. Die Suite ist laut genug, dass eine echte Regression auch wirklich Lärm macht.

Beachte, wofür sie nicht da ist: um zu beweisen, dass das Modell funktioniert. Das kann sie nicht. Tests können Verhalten festnageln, aber keine Qualität. Das ist ein anderer Muskel, und er gehört in eine andere Testumgebung.

Was sich zum Ausborgen lohnt

Wenn du eine lokale KI-App baust und deine Tests Ollama am Laufen haben müssen:

Patche das ollama-Modul am Import-Ort jedes Services mit patch.object(service_module, "ollama") — eine Nahtstelle pro Service, keine Shims nötig.
Gib deiner DB-Schicht einen Pfad-Override und lass sie gegen eine tmp_path-SQLite-Datei laufen.
Nutze eine Autouse-Fixture, um jedes On-Disk-Artefakt (Docs-Ordner, Indexdateien) auf tmp_path umzuleiten, damit kein Test jemals versehentlich echte Daten berührt.
Ziehe für jeden externen Service (Modell, Audio, Workflow-Engine) die Naht an der Prozessgrenze. Teste alles darüber mit echtem Code.

Das Ergebnis ist eine Suite, in der jeder Test in jeder Umgebung läuft, in Millisekunden fertig ist und die tatsächliche Integration jeder von dir geschriebenen Codezeile testet. 351 Tests in etwa drei Sekunden sind keine Optimierung, sondern ein Nebeneffekt davon, dass man nur an den Rändern mockt.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
CI	Continuous Integration	Automatisches Ausführen der Test-Suite bei jedem Push/PR
PR	Pull Request	Eine vorgeschlagene Code-Änderung — wird nur gemerged, wenn die Suite grün ist
API	Application Programming Interface	Die HTTP-Oberfläche, die der TestClient in-process testet
HTTP	HyperText Transfer Protocol	Das Protokoll, das die (in-process) Endpoint-Tests sprechen
RAG	Retrieval-Augmented Generation	Die Retrieval-then-Answer-Pipeline, die getestet wird
KB	Knowledge Base	Die indizierte Dokumentensammlung
FAISS	Facebook AI Similarity Search	Echt in Tests — es ist eine In-Process-Bibliothek
BM25	Best Match 25	Der Keyword-Index — auch echt in Tests
RRF	Reciprocal Rank Fusion	Die Rank-Merging-Formel, die in `test_vector_db.py` abgedeckt wird
SQLite / SQL	(SQL = Structured Query Language)	Die echte, dateibasierte Datenbank, gegen die jeder Progress-Test läuft
DBOS	Database-Oriented Operating System	Die Durable-Workflow-Bibliothek — gepatched, sodass kein Postgres nötig ist
OCR	Optical Character Recognition	Der Fallback für eingescannte PDFs mit eigenen Trigger-Threshold-Tests
SSRF	Server-Side Request Forgery	Die URL-Import-Angriffsklasse, die in `test_docx_url.py` abgedeckt ist
NDJSON	Newline-Delimited JSON	Das Streaming-Format, das die Endpoint-Tests Zeile für Zeile parsen
SHA-256	Secure Hash Algorithm, 256-bit	Der Content-Fingerprint hinter den Re-Ingest-Tests
CRUD	Create, Read, Update, Delete	Die grundlegenden Speicheroperationen für Decks, Quizzes und Maps
PDF / DOCX / PPTX / XLSX / HTML	Portable Document Format / Word / PowerPoint / Excel / HyperText Markup Language	Die Extraktor-Formate mit dedizierten Tests

Das war die Serie. Acht Posts über die Teile von , auf die ich am stolzesten bin — und ein paar, die ich heute anders bauen würde. Wenn irgendetwas davon nützlich für dich war, der Code ist Open Source auf zu finden und der ist auf YouTube.

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

Teil 7 · Gamifying Learning: 25 Badges, Idle-Gap Sessions und eine 90-Tage-Heatmap

Wed, 20 May 2026 00:00:00 +0000

Teil einer Serie über die Entwicklung von . Zuvor: .

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

Ich habe acht Jahre lang ICT an weiterführenden Schulen unterrichtet, bevor ich zum Full-Stack-Developer gewechselt bin. Die zuverlässigste Lektion aus dieser Zeit war unangenehm einfach: Schüler, die beständig da waren, haben gelernt. Die anderen nicht. Talent, Vorwissen, sogar die Motivation an einem bestimmten Tag – all das war der bloßen Anwesenheit nachgelagert.

Der “Dashboard”-Tab in CogniVault ist ein kleiner Versuch, genau das zu fördern. Es ist keine Duolingo-Streak-Panikmaschine. Es sind drei Dinge:

Hero-Statistiken – gesamte Lernzeit, gesamte Sessions, aktueller Streak.
25 Erfolgs-Badges – automatisch erfasst über Chat, Quizzes, Workshops, Flashcards und Mindmaps hinweg.
Eine 90-Tage-Aktivitäts-Heatmap – im GitHub-Stil, mit fünf lila Intensitätsstufen.

Das Ganze besteht nur aus einem kleinen Satz von SQLite-Tabellen und ein paar React-Komponenten. Der interessante Teil ist aber nicht der Code – es sind die Designentscheidungen.

Idle-Gap Sessions

Die schwerste Frage klang eigentlich am einfachsten: Was zählt als eine Lern-Session?

Die naive Antwort ist: “Alles, was zwischen dem Öffnen und Schließen der App passiert.” Aber das ist falsch. Leute lassen Tabs offen. Leute gehen für eine Stunde weg und kommen dann wieder. Leute öffnen die App um 9 Uhr morgens, machen nichts und schauen um 14 Uhr wieder rein.

Die Antwort, bei der ich gelandet bin: Eine Session endet, wenn du 15 Minuten lang inaktiv warst. Stellst du eine Frage und bist dann 16 Minuten inaktiv – das ist eine Session. Kommst du zurück und stellst eine weitere Frage – beginnt eine neue. Der Schwellenwert ist über STUDY_SESSION_IDLE_GAP_SECONDS=900 konfigurierbar.

Die Uhr richtet sich nach den Chat-Nachrichten – dem konversationellen Kern des Lernens in CogniVault. Jede Nachricht verlängert entweder die offene Session (indem sie den ended_at-Zeitstempel und die Nachrichtenanzahl erhöht) oder, falls die Pause seit der letzten Aktivität den Schwellenwert überschreitet, schließt sie diese implizit ab und eröffnet eine neue:

# Simplified from backend/services/progress_tracker.py
def record_message(now: float, idle_gap: int):
 last = most_recent_session()
 if last and (now - last.ended_at) <= idle_gap:
 extend(last, ended_at=now) # same session continues
 else:
 open_session(started_at=now, ended_at=now) # new session begins

Zwei Schreibvorgänge pro Nachricht. Die Dauer einer Session ist ended_at - started_at, was bedeutet, dass “Gesamtzeit” die aktive Zeit widerspiegelt, nicht “hatte einen Tab offen”. Das ist die einzige Zahl, die wirklich etwas aussagt. (Aktionen im Study Hub – Quizversuche, Karteikarten umdrehen, Mindmap-Exporte – werden als eigene Events erfasst und fließen in die Badge-Metriken unten ein; die Session-Uhr selbst bleibt nachrichtengetrieben und ehrlich.)

25 Badges, nicht 250

Die meisten gamifizierten Apps überfluten dich regelrecht mit Erfolgen. Es gibt einen Grund dafür: mehr Badges, mehr Dopamin, mehr täglich aktive Nutzer. Der Preis dafür ist, dass jedes Badge weniger bedeutet – irgendwann wird die ganze Schicht nur noch zur Tapete.

Ich habe CogniVault auf 25 limitiert, aufgeteilt auf die fünf Aktivitätsbereiche:

10 für Chat & Lerngewohnheiten (erste Frage, 10 Nachrichten an einem Tag, 100 insgesamt, eine Stunde Gesamtlernzeit, 3- und 7-Tage-Streaks, eine 30-minütige Deep-Dive-Session, Night-Owl- und Early-Bird-Sessions, erste Nutzung des Scope-Filters)
4 für Quizzes (erstes Quiz, perfektes Ergebnis, Bestehen auf fortgeschrittenem Schwierigkeitsgrad, 10 Quizzes)
4 für Workshops (erste Outline, erste abgeschlossene Lektion, erster abgeschlossener Workshop, 5 abgeschlossen)
4 für Flashcards (erstes Deck, 50 umgedrehte Karten, ein Deck komplett gemeistert, 5 Decks)
3 für Mindmaps (erste Mindmap, erster Export, 5 Mindmaps)

Jedes Badge hat ein einzeiliges Freischaltkriterium, das bei relevanten Events automatisch ausgewertet wird. Nichts Manuelles, nichts, was der Nutzer “einfordern” muss. Sie tauchen einfach auf.

Und die Definitionen sind gar kein Code – sie sind Daten. Alle 25 leben in einer JSON-Datei. Jeder Eintrag benennt die Metrik, die er beobachtet, und das zu erreichende Ziel:

{
 "code": "card_reviewer",
 "name": "Card Reviewer",
 "icon": "🃏",
 "metric": "total_card_flips",
 "target": 50
}

Ein einzelner Evaluator liest die aktuellen Statistiken aus, vergleicht jede Definition mit ihrer Metrik, gleicht sie mit bereits verdienten Badges ab und fügt neue Freischaltungen in die progress.db ein. Ein 26. Badge hinzuzufügen, bedeutet, einen JSON-Eintrag hinzuzufügen, nicht neue Logik zu schreiben. Mehrere Badges bilden Leitern – jedes weiß, welches Badge das “nächste Level” ist, was den Schubs in der Detailansicht zum nächsten Ziel antreibt.

Die Heatmap

Auf die 90-Tage-Heatmap bin ich am meisten stolz, und sie ist gleichzeitig das Einfachste. Es ist ein 13×7-Raster aus Zellen, eine pro Tag, farblich markiert nach der Gesamtlernzeit an diesem Tag.

Fünf Intensitätsstufen:

level 0 — no activity
level 1 — under 15 minutes (a quick check-in)
level 2 — 15-60 minutes (a focused session)
level 3 — 1-3 hours (substantial study)
level 4 — 3+ hours (a marathon)

Die Daten sind konzeptionell eine einzige Aggregation über die Sessions-Tabelle:

SELECT date(started_at) AS day,
 SUM(ended_at - started_at) AS seconds
FROM study_sessions
WHERE started_at >= date('now', '-90 days')
GROUP BY day;

Das Backend füllt die fehlenden Tage mit Nullen auf, sodass das Frontend immer genau 90 Einträge erhält. Eine kleine clientseitige Funktion ordnet die Tagessummen in die fünf Level ein. Wenn du auf eine beliebige Zelle klickst, öffnet sich ein DayDetailModal mit den Zahlen dieses Tages – Lernzeit, Sessions, Nachrichten – sowie allen Badges, die an diesem Tag verdient wurden.

Der Grund, warum ich diese Komponente liebe: Sie macht die Textur einer Lerngewohnheit sichtbar. Streaks sind toll, aber ein Streak ist nur eine Zahl. Eine Heatmap zeigt dir, dass du am Wochenende härter lernst, oder dass du den ganzen Monat über langsam abgebaut hast, oder dass die Lücke zwischen deinem letzten “Level 4-Tag” und heute größer ist, als du dachtest. Sie spiegelt etwas wider, worauf der Nutzer reagieren kann.

Was ich bewusst weggelassen habe

Drei Dinge, die du in den meisten gamifizierten Apps finden würdest, fehlen in CogniVault absichtlich:

Streak-Panik. Kein “Dein Streak ist in Gefahr!"-Popup. Keine Regeln für Streak-Freezes. Keine gelben Ausrufezeichen. Der Streak wird angezeigt – das ist der gesamte Feedback-Loop. Wenn ein Nutzer seinen Streak bricht, dann bricht er ihn eben. Erwachsene brauchen keine Shaming-UX.
Leaderboards. Das ist eine lokale Einzelnutzer-App. Es gibt keinen globalen Vergleich. (Und den sollte es auch nicht geben – Leaderboards optimieren beim Lernen das Falsche.)
Konfetti, Fanfaren, Push-Benachrichtigungen. Ein neu verdientes Badge taucht auf dem Quiz-Ergebnisbildschirm und im Dashboard-Raster auf. Das ist die ganze Feier. Alles, was größer ist, stiehlt dem Nutzer die Aufmerksamkeit zum Nutzen der App, nicht zu seinem eigenen.

Das allgemeine Prinzip: Miss, was wichtig ist, mach es sichtbar, aber ohne zu nerven. Registriere, dass du wiedergekommen bist. Spiegele dir das wider. Tu nicht so, als ob es dich mehr interessiert, als es das tatsächlich tut.

Was das Dashboard nicht zu optimieren versucht

Eine häufige Falle bei diesen Dashboards ist die umgekehrte Kausalität: Der Nutzer fängt an, die Metrik zu spielen, anstatt die eigentliche Sache zu tun. Ein täglicher Fragenzähler zum Beispiel führt dazu, dass Nutzer eine irrelevante Frage pro Tag stellen, um ihren Streak am Leben zu halten.

Deshalb ist die Hürde absichtlich an genau einer Stelle sehr niedrig und überall sonst hoch. Es gibt ein Badge, das keinen Aufwand erfordert – “Erste Frage”, das man für die allererste Nachricht bekommt –, weil jedes Spiel eine Einstiegsrampe braucht, die beweist, dass das System funktioniert. Danach werden die Metriken schwer zu manipulieren, ohne die eigentliche Arbeit zu tun:

Gesamtlernzeit – sammelt sich nur während aktiver Nutzung an, mit Idle-Gap-Abschaltungen.
Sessions – um mehr hinzuzufügen, muss man tatsächlich separate Arbeitsphasen starten.
Badges – fast alle erfordern Tiefe (100 Nachrichten, ein Quiz meistern, ein Deck perfekt beherrschen, 5 Workshops abschließen), nicht nur oberflächliches Antippen.
Heatmap-Intensität – erfordert anhaltendes Engagement an einem bestimmten Tag.

Implementierung: bewusst klein

Der Gamification-Kern besteht aus drei SQLite-Tabellen –

study_sessions (id, started_at, ended_at, message_count)
message_events (id, sent_at, session_id, had_scope_filter, had_attachments)
achievements_earned (code, earned_at)

— plus die JSON-Badge-Definitionen, ein Evaluator-Modul und eine Handvoll React-Komponenten (SummaryCards, AchievementGrid, ActivityHeatmap, DayDetailModal). Die gleiche progress.db-Datei hat mittlerweile weitere Tabellen für die gespeicherten Quizzes, Workshops, Decks und Mindmaps des Study Hubs bekommen – aber die Badge-und-Session-Maschinerie selbst ist nur ein paar hundert Zeilen lang geblieben.

Daran ist nichts Ausgefallenes. Das Dashboard funktioniert, weil die Designentscheidungen richtig sind, nicht weil die Implementierung raffiniert ist.

Fazit

Wenn du ein Lern-Tool baust – oder ein beliebiges Tool, das von den Gewohnheiten der Nutzer lebt –, dann setze Gamification bewusst ein. Wähle die Metriken, die das widerspiegeln, was du wirklich fördern willst. Begrenze die Anzahl der Erfolge. Verzichte auf die Streak-Panik-UX. Mach die Textur der Nutzung sichtbar, ohne dass die App verzweifelt wirkt.

Oder direkter gesagt: Bau kein Duolingo. Bau ein Dashboard, auf das der Nutzer ab und zu schaut und das er dann wieder schließt, mit dem leichten Gefühl, weitermachen zu wollen. Das ist der ganze Job.

Anhang: Abkürzungen in diesem Beitrag

Abkürzung	Vollform	Bedeutung
UX	User Experience	Wie sich das Produkt anfühlt – genau das, was durch Streak-Panik-Mechaniken geopfert wird
ICT	Information and Communications Technology	Das Fach, das ich acht Jahre lang unterrichtet habe, bevor ich zum Full-Stack gewechselt bin
SQLite	(SQL = Structured Query Language)	Eine komplette relationale Datenbank in einer einzigen Datei, `progress.db`
JSON	JavaScript Object Notation	Das Datenformat, in dem die 25 Badge-Definitionen liegen
UI	User Interface	Die Dashboard-Oberfläche: Statistiken, Raster, Heatmap

Als Nächstes: .

Teil 6 · Der Mindmap-Renderer: Was mich das händische Bauen von SVG gelehrt hat (und warum v2 React Flow nutzt)

Fri, 15 May 2026 00:00:00 +0000

Teil einer Serie über die Entwicklung von . Zuvor: .

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

Der Study Hub von CogniVault hat vier Modi. Drei davon – Quiz, Workshop, Flashcards – haben eine Listenform. Der vierte, Mindmap, nicht. Es ist ein Baum von Konzepten, die von einem zentralen Thema ausgehen, und ich wollte, dass er:

Optisch so sauber ist, dass der Nutzer ihn sich tatsächlich gerne ansieht.
Interaktiv ist: Verschieben, Zoomen, Erkunden.
Hochauflösend als PNG und PDF exportiert werden kann.

Dieser Beitrag ist die ehrliche Version davon, wie dieser Renderer gebaut wurde – und zwar zweimal. Version eins war reines, händisch gebautes SVG ohne Graphen-Bibliothek, und sie wurde veröffentlicht. Version zwei, die heute in der Codebasis steht, baut auf @xyflow/react (React Flow) und einem dagre Auto-Layout auf. Ich glaube, beide Entscheidungen waren zu dem Zeitpunkt, als sie getroffen wurden, richtig. Und der Weg dazwischen hat mir mehr über “Build vs. Buy” (Selber bauen oder einkaufen) beigebracht als jede der beiden Versionen für sich genommen.

Runde eins: Händisch bauen

Mein erster Instinkt war, wie bei jedem anderen auch, sofort an Tag eins zu einer Bibliothek zu greifen. Ich habe widerstanden, und zwar aus guten Gründen: Das Standard-Styling hätte sowieso komplett angepasst werden müssen, das gewünschte Layout war simpel, für den Export hätte man ohnehin externe Abhängigkeiten gebraucht, und die Bundle-Größe ist auch nicht zu verachten. Für die kleinen Bäume, die Gemma generiert, schien SVG völlig ausreichend – es lässt sich mit dem viewBox-Attribut verschieben und zoomen, zeichnet beliebige Formen, lässt sich als String serialisieren und sauber rastern.

Also war v1 reines SVG. Und der Kern davon war wirklich klein.

Radial-Layout in 40 Zeilen

Ein radiales Layout platziert die Wurzel in der Mitte und ordnet die Kinder in konzentrischen Ringen an:

type Node = { id: string; label: string; children: Node[] };
type Placed = Node & { x: number; y: number; angle: number };

function layout(root: Node, radiusStep = 180): Placed[] {
 const placed: Placed[] = [];

 function place(
 node: Node,
 depth: number,
 fromAngle: number,
 toAngle: number,
 ) {
 if (depth === 0) {
 placed.push({ ...node, x: 0, y: 0, angle: 0 });
 } else {
 const angle = (fromAngle + toAngle) / 2;
 placed.push({
 ...node,
 x: depth * radiusStep * Math.cos(angle),
 y: depth * radiusStep * Math.sin(angle),
 angle,
 });
 }

 const slice = (toAngle - fromAngle) / Math.max(node.children.length, 1);
 node.children.forEach((child, i) =>
 place(
 child,
 depth + 1,
 fromAngle + i * slice,
 fromAngle + (i + 1) * slice,
 ),
 );
 }

 place(root, 0, 0, 2 * Math.PI);
 return placed;
}

Jede Ebene erbt ein Winkelsegment von ihrem Elternteil und unterteilt es unter ihren Kindern. Verschieben (Pan) und Zoomen waren reine viewBox-Arithmetik – keine Transformationsmatrizen, keine Event-Bibliothek, nur Zahlen. Kanten waren quadratische Bézier-Kurven, die in Richtung Zentrum gezogen wurden. Es sah gut aus, war schnell, und der gesamte Renderer passte bequem in eine einzige Komponente.

Der Export-Trick, den man immer noch kennen sollte

Um ein SVG ohne Abhängigkeiten als PNG zu exportieren, lässt man den Browser die ganze Arbeit machen:

SVG DOM ─► XMLSerializer ─► string ─► <img> ─► <canvas> ─► PNG blob

Serialisiere das SVG zu einem String, lade es in ein Image, zeichne dieses Bild auf ein skaliertes <canvas> und frag das Canvas nach einem PNG. Schriftarten, Anti-Aliasing, currentColor – der Browser löst das alles nativ auf. Wenn deine Grafik ein SVG-Element ist, ist das immer noch die sauberste Export-Pipeline, die es gibt, und ich würde sie ohne Zögern wieder verwenden.

Ein Detail von v1 hat bis heute komplett unverändert überlebt: der Speichern-Flow. Anstatt des klassischen “Direkt in den Downloads-Ordner”-Erlebnisses laufen Exporte über die File System Access API (showSaveFilePicker), wo der Browser das unterstützt, mit einem Anker-Tag-Download-Fallback für Firefox und Safari. Ein echter “Speichern unter…"-Dialog, ganz ohne Electron. Dieser Helfer (lib/saveBlob.ts) bedient jetzt auch die Quiz- und Workshop-Exporte.

Die Anforderungen, die v1 gebrochen haben

Dann traf das Feature auf seine Nutzer (naja – auf mich, als ich es beim Lernen ernsthaft benutzte), und es tauchten drei Anforderungen auf, mit denen die elegante, handgemachte Version nicht gut zurechtkam:

“Lass mich diesen Knoten bewegen.” Ein generiertes Layout ist ein Startpunkt; eine nützliche Mindmap ist eine, die du so anordnest, dass sie deiner Denkweise entspricht. Die Knoten von v1 waren an ihren berechneten Positionen fixiert. Drag-and-Drop hinzuzufügen hätte bedeutet, Hit-Testing, Drag-State und Positions-Persistenz von Grund auf neu zu bauen – genau die unglamouröse Interaktions-Maschinerie, für die Graphen-Bibliotheken überhaupt existieren.
Text wollte HTML sein. SVG <text> bricht nicht um. Lange Konzept-Labels erforderten manuelles Umbrechen, Ausmessen und Abschneiden von Zeilen – ein ständiger Kampf. HTML-Knoten (echte <div>s mit CSS) übernehmen Zeilenumbrüche, Ellipsen und Theming umsonst.
Radial war doch nicht das beste Lese-Layout. Für die breiten und flachen Bäume, die Gemma tatsächlich generiert, liest sich ein Links-nach-Rechts- oder Von-Oben-nach-Unten-Baum (die Art, die eine Layout-Engine wie dagre berechnet) besser als Ringe. Und als Layouts umschaltbar wurden, wurde “Auto-Layout plus gemerkte manuelle Anpassungen” das natürliche Modell.

Ich hätte all das auf der SVG-Basis bauen können. Aber schau dir die Liste an: Viewport-Management, Drag-and-Drop für Knoten, HTML-Knoten in einem Graphen-Canvas, austauschbare Layouts. Das ist exakt das Feature-Set von React Flow. In v1 wäre die Bibliothek nur ein Wrapper um Dinge gewesen, die ich nicht brauchte. Für v2 waren meine Anforderungen genau zu den Dingen herangewachsen, die sie gut kann.

Also habe ich meine Meinung geändert.

Runde zwei: React Flow + dagre

Der heutige Renderer (frontend/src/components/study/mindmaps/):

@xyflow/react (React Flow) liefert das Canvas: natives Panning/Zoomen, ziehbare Knoten, einen Steuerungsblock im Minimap-Stil und Dark-Mode-Unterstützung via colorMode.
dagre berechnet das automatische Layout, mit einem sichtbaren Schalter zwischen Links-nach-Rechts und Von-Oben-nach-Unten. Die Baum-zu-Graph-Konvertierung ist eine winzige Pure Function.
Benutzerdefinierte HTML-Knoten tragen das Design-System: Die Wurzel bekommt einen Verlauf, Themen eine Tönung, Blätter bleiben dezent – und Text bricht um, wie Text umbrechen sollte.
Gezogene Positionen bleiben erhalten. Das Bewegen eines Knotens löst einen Speicher-Vorgang aus; öffnest du die Map neu, wird deine Anordnung wiederhergestellt. Ein “Reset layout”-Button löscht die gespeicherten Positionen und kehrt zum dagre-Auto-Layout zurück. Die Layout-Wahl und die Positionen leben zusammen mit der Mindmap in SQLite.
Der Export wurde an die neue Realität angepasst. Die Knoten sind jetzt HTML, also funktioniert der SVG-Serialisierungs-Trick aus v1 nicht mehr. Der PNG-Export nutzt html-to-image über den React-Flow-Viewport, passgenau auf die Knotengrenzen zugeschnitten, unabhängig vom aktuellen Zoom. Das PDF bettet dieses PNG über ein lazy-geladenes jsPDF ein. Der Markdown-Export ist ein rekursiver Durchlauf des Baums ohne externe Abhängigkeiten. Ja – v2 nutzt genau die Bibliothek (html-to-image), auf deren Vermeidung ich in v1 noch stolz war. Die Anforderungen haben sich geändert; und damit auch der Trade-off.

Was mich die Reise wirklich gelehrt hat

Ich habe hin- und herüberlegt, wie ich diesen Beitrag schreiben soll, denn die Geschichte von v1 (“Schau mal, wie wenig Code man braucht!”) ist schmeichelhafter. Aber die Wahrheit aus beiden Versionen ist die viel nützlichere Lektion:

Zuerst selber bauen war trotzdem richtig. v1 war an einem Wochenende fertig, hat mir die wahre Form des Problems gezeigt (Layout, Viewport und Export sind getrennte Baustellen) und kostete mich nichts, es wegzuwerfen, weil es so klein war. Hätte ich mit React Flow angefangen, hätte ich eine Bibliothek konfiguriert, bevor ich das Problem überhaupt verstanden hatte.
Bibliotheken verdienen sich ihren Platz erst, wenn deine Anforderungen auf ihr Feature-Set zulaufen – nicht vorher. In dem Moment, als “Zieh Knoten und merk dir, wo ich sie hingelegt habe” zur Anforderung wurde, drehte sich die Build-vs-Buy-Rechnung komplett um.
Einige Teile überleben das Rewrite. Der Speicher-Dialog-Helfer, der Markdown-Durchlauf, der Instinkt, Exporte auf die Inhaltsgrenzen zuzuschneiden – all das wurde übernommen. Rewrites sind selten total.
Die nativen Pipelines des Browsers sollte man kennen, auch wenn man sie am Ende nicht nutzt. SVG → Canvas → PNG ist immer noch der beste Export-Trick ohne externe Abhängigkeiten in der Frontend-Entwicklung. Er funktioniert nur nicht mehr an dem Tag, an dem deine Knoten HTML werden.

Fazit

“Build or buy” (Selber bauen oder kaufen) ist eine Funktion von Anforderungen – und Anforderungen bewegen sich. Bau selbst, solange das Problem klein ist und du noch lernst, wie es aussieht. Kauf ein, wenn deine Feature-Liste anfängt, sich wie die README der Bibliothek zu lesen. Und wenn du wechselst, schreib auf, warum, damit die nächste Person (oder dein zukünftiges Ich) weiß, dass es keine Unentschlossenheit war. Es war einfach der Plan, der erwachsen geworden ist.

Anhang: Abkürzungen in diesem Beitrag

Abkürzung	Vollform	Bedeutung
SVG	Scalable Vector Graphics	Das eingebaute Vektor-Zeichenformat des Browsers – das komplette Fundament von v1
PNG	Portable Network Graphics	Das Rasterbildformat, das bei Exporten herauskommt
PDF	Portable Document Format	Der druckfertige Export, gebaut durch Einbetten des PNGs
DOM	Document Object Model	Die Live-Repräsentation der Seite im Browser – das, was `html-to-image` in v2 rastert
HTML / CSS	HyperText Markup Language / Cascading Style Sheets	Woraus die Knoten in v2 bestehen – und warum ihr Text automatisch umbricht
API	Application Programming Interface	Wie in File System Access API, die echte “Speichern unter…"-Dialoge bereitstellt
UI / UX	User Interface / User Experience	Die Anforderung, einen Knoten ziehen zu können, die das Rewrite ausgelöst hat
JSON	JavaScript Object Notation	Die Baumstruktur, die Gemma für jede Mindmap generiert (siehe vorheriger Beitrag)
SQLite	(SQL = Structured Query Language)	Die Single-File-Datenbank, in der Layout-Entscheidungen und Knotenpositionen persistieren

Als Nächstes: .

Teil 5 · Zuverlässiges JSON aus einem lokalen LLM bekommen

Sun, 10 May 2026 00:00:00 +0000

Teil einer Serie über die Entwicklung von . Zuvor: .

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

Der Study Hub von CogniVault generiert aus deinen Dokumenten vier Arten von strukturierten Artefakten: Quizzes, mehrteilige Workshops, Flashcard-Decks und Mindmaps. Alle vier benötigen ein Modell, das strukturiertes JSON zurückgibt, keinen Fließtext. Alle vier laufen auf Gemma 4, das lokal über Ollama ausgeführt wird. Und alle vier würden viel zu oft scheitern, wenn ich darauf vertrauen würde, dass das Modell “einfach JSON zurückgibt”.

Hier ist das defensive Muster, das diese Ausfallrate auf nahe null drückt – und was man mit den Fällen macht, die trotzdem noch durchrutschen.

Das Muster

1. Retrieve → hybrid search restricted by user-selected scope
2. Prompt → strict schema-by-example with explicit count + shape rules
3. Generate → ollama.chat with format="json" (grammar-constrained)
4. Parse → json.loads, tolerant of object / array / fenced shapes,
 with a trailing-comma repair pass
5. Validate → drop malformed items rather than fail the whole batch
6. Retry → the workshop outline retries once with a stronger prompt
7. Persist → SQLite (progress.db) so the user can come back later

Jeder Generator in CogniVault folgt diesem Ablauf. Die interessanten Schritte sind 2, 4 und 5.

Schritt 3: `format="json"` leistet echte Arbeit

Ollama bietet eine format="json"-Option, die dem Modell während des Samplings einen Grammatik-Constraint (Einschränkung) auferlegt. Der Decoder gibt keine Tokens aus, die die Ausgabe zu ungültigem JSON machen würden. Das ist nicht perfekt – Schemata umfassen mehr als nur “gültiges JSON”, und das Modell kann immer noch wohlgeformten Müll produzieren – aber es eliminiert die gesamte Klasse von “Das Modell hat angefangen, Text vor der schließenden Klammer zu schreiben”-Fehlern.

Wenn dein lokaler LLM-Stack eine Grammatik-Option unterstützt (Ollama, llama.cpp, vLLM usw.), schalte sie ein. Sie ist nicht umsonst (Sampling wird etwas langsamer), aber die Verbesserung bei den Fehlerarten ist enorm. Ohne sie wirst du dein gesamtes Fehlerbudget für abgeschnittene Objekte ausgeben.

Schritt 2: Ein Schema-im-Prompt, an das sich das Modell auch halten kann

format="json" garantiert, dass die Struktur der Ausgabe JSON ist. Es sagt nichts darüber aus, ob das JSON auch zu deinem Domain-Schema passt. Das ist die Aufgabe des Prompts.

Das Muster, das für mich funktioniert: Anstatt ein formales JSON-Schema reinzuwerfen und zu sagen “halte dich daran”, baue ein ausgefülltes Beispiel ein, das dem Modell die exakte Form und explizite Mengenangaben zeigt. Hier ist das Herzstück des echten Quiz-Templates von CogniVault (es liegt als bearbeitbare Markdown-Datei in backend/prompts/quiz.md):

Output ONLY a single JSON object — no prose, no markdown fences,
no text outside the JSON.

NUMBER OF QUESTIONS: EXACTLY $num_questions. This is a hard requirement.

OUTPUT SCHEMA:
{
 "questions": [
 {
 "type": one of [$types_csv],
 "question": the question text (string, no leading numbering),
 "options": array of strings (length 4 for mcq, length 2 for true_false),
 "correct_index": integer index into options (0-based),
 "explanation": 1-2 sentence explanation of the correct answer
 },
 ... exactly $num_questions entries
 ]
}

Ein paar Entscheidungen, die wichtig sind:

Zeig die Form, beschreibe sie nicht. “Jedes Item hat ein type-Feld” wird viel öfter ignoriert als ein wörtliches Beispiel.
Lege die Anzahl fest. “EXACTLY 10” – wiederholt, in Großbuchstaben, als harte Anforderung – ist viel zuverlässiger als “ungefähr 10”.
Verwende Indizes, keine Wiederholungen. Die richtige Antwort ist correct_index, ein Integer, der auf die options verweist – und nicht noch einmal der Antworttext. Wiederholter Text lädt zu Paraphrasierungen ein (“Paris” vs. “Paris, Frankreich”), und dann geht dein Grading-Vergleich kaputt.
Ein Artefakt pro Aufruf. Ich habe versucht, einen kompletten Workshop (Outline + jede Lektion) in einem Aufruf zu generieren. Die Qualität des Modells nimmt rapide ab, je länger die Antwort wird. Die Aufteilung in “Outline zuerst, Lektionen nach Bedarf” ist die weiter unten beschriebene Zwei-Phasen-Strategie.

Schritt 4: Tolerant parsen

Selbst mit format="json" überleben in der Praxis zwei Parsing-Probleme.

Die Struktur-Überraschung. Das hier hat mich in der Produktion erwischt: Ich war davon ausgegangen, dass das Modell ein reines JSON-Array von Fragen zurückgeben würde. Mit format="json" gibt Gemma aber beständig ein Objekt zurück – {"questions": [...]} – und eine Zeit lang hat mein Parser nur das Array akzeptiert. Das Ergebnis: Ein 502-Fehler bei jeder Quiz-Generierung, bis ich es gefunden hatte. Die Lösung ist ein Parser, der dem Modell entgegenkommt:

# Simplified from backend/services/quiz_generator.py
def extract_items(raw: str) -> list | None:
 for candidate in (raw, extract_json_object(raw), extract_json_array(raw)):
 if candidate is None:
 continue
 data = load_json_lenient(candidate)
 if isinstance(data, list):
 return data # bare array
 if isinstance(data, dict):
 items = data.get("questions") # the expected object shape
 if isinstance(items, list):
 return items
 return None

Lexikalische Ausrutscher. Manchmal rutscht ein nachgestelltes Komma durch. Die Reparatur ist absichtlich eng gefasst – ein Regex-Durchlauf, danach aufgeben:

def load_json_lenient(text: str):
 try:
 return json.loads(text)
 except json.JSONDecodeError:
 repaired = re.sub(r",(\s*[\]}])", r"\1", text) # strip trailing commas
 try:
 return json.loads(repaired)
 except json.JSONDecodeError:
 return None

Ich versuche nicht, Klammern auszugleichen, abgeschnittene Strings zu vervollständigen oder fehlende Felder zu erraten. Entweder ist die Ausgabe mit einem Trailing-Comma-Pass und etwas Substring-Extraktion reparierbar, oder eben nicht – und dann gehen wir zu Schritt 5.

Schritt 5: Fehlerhafte Items verwerfen, nicht den ganzen Batch scheitern lassen

Das war die Entscheidung, mit der ich am längsten zu kämpfen hatte, bis ich meinen Frieden damit gemacht habe.

Wenn das Modell 10 Quizfragen zurückgibt, aber bei Nummer 7 das options-Feld fehlt, ist die Versuchung groß, einen Fehler auszuwerfen und den ganzen Batch neu zu generieren. Tu das nicht. Validiere jedes Item einzeln und verwirf diejenigen, die fehlschlagen.

# CogniVault does this with explicit field checks into a dataclass;
# pydantic works just as well.
questions = []
for raw_item in parsed_items:
 q = validate_item(raw_item, allowed_types) # returns None if malformed
 if q is not None:
 questions.append(q)

Der Nutzer bekommt 9 Fragen statt 10. Das fällt ihm nicht auf. Die gesamte Generierung neu zu starten, um Frage 7 zu reparieren, kostet 30 Sekunden und führt vielleicht zu neuen Fehlern in den Fragen 1-6. Der “Dropped-Item”-Ansatz ist für die UX einfach streng genommen besser. (Das Modell schießt übrigens auch manchmal über das Ziel hinaus – die validierte Liste wird dann einfach auf die angeforderte Menge gekürzt.)

Schritt 6: Die Outline darf es einmal neu versuchen

Workshops sind die Ausnahme, die die Regel bestätigt. Ein Workshop ist eine strukturierte Outline (Titel, Zusammenfassung, Lektionsliste) plus der Inhalt jeder Lektion. Die Outline muss parsbar sein – bei einem Inhaltsverzeichnis gibt es keinen Teilerfolg. Deshalb löst ein Parsing-Fehler hier genau einen Retry aus, bei dem der Prompt noch einmal mit einer strengen Erinnerung geschickt wird: “Your previous response was unparseable. Output ONLY a single valid JSON object.” Wenn der zweite Versuch auch fehlschlägt, bekommt der Nutzer eine klare Fehlermeldung mit dem Vorschlag, den Scope etwas einzuengen.

Ein Retry, nicht drei. Drei Retries, wenn das Modell ohnehin verwirrt ist, verschwenden nur Sekunden und Strom.

Die Lektionen selbst sind interessanterweise gar kein JSON. Ein Lektionstext ist Fließtext – ihn in einen JSON-String zu zwingen, brächte nichts und würde nur Escaping-Kopfschmerzen verursachen. Lektionen werden als reines Markdown generiert und durchlaufen dann einen kleinen Cleanup-Pass, die Chat-Floskeln entfernt, die das Modell trotz gegenteiliger Anweisungen manchmal hinzufügt (“I hope this helps!”, “Let me know if…”). Andere Ausgabe, anderer Vertrag.

Zwei-Phasen-Ansatz: Outline zuerst, Lektionen nach Bedarf

Workshops nutzen ein zweistufiges Generierungsmuster:

Pass 1 — generate outline: {"title": ..., "lessons": [{"title": ...}, ...]} (cheap, JSON)
Pass 2 — for each lesson: a full Markdown lesson body (on demand)

Die Outline ist schnell da und lässt den Nutzer sofort die Struktur des Workshops sehen. Jede Lektion wird erst generiert, wenn der Nutzer sie öffnet – was bedeutet, dass der Nutzer gerade Lektion 1 liest, während er noch entscheidet, ob er Lektion 5 überhaupt haben möchte. Die Gesamt-Wartezeit bis zum “ersten nützlichen Inhalt” ist so selbst bei einem Workshop mit 10 Lektionen winzig.

Das ist genau der gleiche architektonische Kniff, den die Chat-Seite mit dem anwendet: Teile eine langsame Operation in einen winzigen schnellen Teil und einen größeren langsamen Teil auf, und gib dem Nutzer den schnellen Teil sofort.

Was ich bisher beim Bauen dieser Generatoren gelernt habe

Ein paar destillierte Prinzipien aus den vier Generatoren:

Nutze die Grammatik-Option in deinem Inference-Stack. Versuch erst gar nicht, JSON aus einem frei formulierenden Decoder herauszulocken.
Nagel jeden Quantifikator im Prompt fest. “Exactly 10”, “exactly 4 options”, “one or two sentences”. Vage Mengenangaben = inkonsistenter Output.
Verlass dich nicht auf die oberste Struktur-Ebene. Grammatik-eingeschränktes Gemma mag Objekte; dein Code erwartet vielleicht Arrays. Akzeptiere beides – der Parser ist billiger, als sich darauf zu verlassen, dass das Modell die erwartete Struktur liefert.
Verwerfen, nicht scheitern lassen. Ein verlustbehafteter Erfolg schlägt spröde Perfektion.
Ein Retry, nie mehr. Wenn zwei Versuche kein gültiges Ergebnis liefern, ist der Prompt falsch, nicht das Modell.
Teile große Generierungen auf. Outline + Lektionen. Skelett + Körper. Zwei kleine Aufrufe schlagen einen großen fast jedes Mal. Und wenn ein Teil der Ausgabe natürlicher Fließtext ist, lass ihn auch Fließtext sein.

Lokale LLMs sind im Jahr 2026 gut genug, dass strukturierte Generierung für Features auf Produktionsniveau wirklich nutzbar ist. Sie sind allerdings nicht so gut, dass du auf das defensive Gerüst verzichten könntest. Das obige Gerüst macht insgesamt vielleicht 80 Zeilen Code in allen vier Generatoren aus, und das ist genau der Unterschied zwischen “Demo-Qualität” und “Ich vertraue dem genug, um es zu shippen.”

Anhang: Abkürzungen in diesem Beitrag

Abkürzung	Vollform	Bedeutung
JSON	JavaScript Object Notation	Das strukturierte Textformat, das die Generatoren produzieren müssen
LLM	Large Language Model	Ein neuronales Netz, das auf großen Textmengen trainiert wurde, um Sprache zu lesen und zu generieren
AI	Artificial Intelligence	Software, die Aufgaben ausführt, für die normalerweise menschliche Intelligenz erforderlich ist
MCQ	Multiple-Choice Question	Eine der zwei Arten von Quizfragen (die andere ist True/False)
UX	User Experience	Warum 9 gültige Fragen besser sind als ein Neu-Generierungs-Fehler
SQLite	(SQL = Structured Query Language)	Die Single-File-Datenbank, in der generierte Artefakte gespeichert werden
DBOS	Database-Oriented Operating System	Die Bibliothek für dauerhafte Workflows aus dem vorherigen Beitrag
HTTP 502	Bad Gateway (HyperText Transfer Protocol status code)	Der Fehler, den mein reiner Array-Parser warf, bis ich Gemmas Objektform akzeptierte

Als Nächstes: — was mich das händische Bauen eines SVG-Radial-Layouts gelehrt hat und warum Version zwei trotzdem React Flow nutzt.

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 3 · Zwei-Phasen-Streaming: Zeigen, wie das Modell denkt, bevor es handelt

Thu, 30 Apr 2026 00:00:00 +0000

Teil einer Serie über den Aufbau von . Zuvor: . Alle Abkürzungen werden vollständig im Anhang am Ende der Seite erklärt.

Als ich Gemma 4 zum ersten Mal mit in CogniVault verkabelt habe, fühlte sich der Chat langsam an. Nicht laggy — langsam auf eine Art, die schlimmer ist als laggy. Der User tippt eine Frage ein. Der Cursor sitzt da und macht nichts. Dann, irgendwann, fällt eine Antwort aus dem Nichts.

Das Modell war nicht untätig. Es hat nachgedacht. Gemma 4 hat einen Chain-of-Thought-Modus, der einen (manchmal langen) Gedankengang produziert, bevor die finale Antwort kommt. Bei einem einphasigen Agenten-Stream passiert dieses ganze Nachdenken innerhalb der Agenten-Loop — still und heimlich — bevor irgendwelche Tool-Aufrufe laufen oder irgendwelche Tokens an die UI gesendet werden.

Also habe ich den Aufruf in zwei Phasen unterteilt.

Die Struktur

POST /rag
 │
 ├── Phase 1 — Direkter Ollama-Aufruf, Thinking aktiviert
 │ stream: {"type":"thinking","data":"..."} (Reasoning-Tokens)
 │
 └── Phase 2 — Strands Agent (Thinking deaktiviert)
 stream: {"type":"metadata","data":{...}} (Quellenangaben, sobald die Suche läuft)
 stream: {"type":"text","data":"..."} (Antwort-Tokens)
 stream: {"type":"memory","data":{...}} (End-of-Stream: Speicherverbrauch der Session)

Der Endpoint streamt Newline-Delimited JSON (NDJSON): Jede Zeile im Response-Body ist ein eigenständiger JSON-Umschlag mit einem type und einem data. Das Frontend entscheidet anhand des type und rendert entsprechend: ein ausklappbares Reasoning-Panel für die Thinking-Tokens, die Hauptnachrichten-Blase für die Text-Tokens und eine Sidebar-Card pro Quelle.

Der User sieht das Modell sofort anfangen zu denken. Die Latenz bis zum ersten Byte sinkt von “lang genug, um sich zu fragen, ob es abgestürzt ist” zu “sofort”. Die Gesamtzeit bis zur finalen Antwort ändert sich nicht. Aber die gefühlte Geschwindigkeit schon.

Phase 1 — Nur Nachdenken

Phase 1 ist ein einzelner direkter Aufruf an Ollama mit aktiviertem Thinking. Er bekommt exakt das, was auch Phase 2 sehen wird — denselben System-Prompt, die aktuelle Frage und alle angehängten Bilder —, sodass die Argumentation die Realität widerspiegelt. Nur die Reasoning-Tokens werden konsumiert; was auch immer an Antworttext Phase 1 zu produzieren beginnt, wird verworfen, weil wir nicht wollen, dass eine halbfertige Antwort mit der echten konkurriert.

# Simplified from backend/services/rag_agent.py
client = ollama.AsyncClient(host=settings.ollama_host)
stream = await client.chat(
 model=settings.llm_model,
 messages=[
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": query, "images": images},
 ],
 options={"thinking": True},
 stream=True,
)
async for chunk in stream:
 if chunk.message.thinking:
 yield envelope("thinking", chunk.message.thinking)

Phase 1 ist absichtlich Best-Effort: Jeder Fehler hier wird einfach geschluckt und geloggt, und der Stream geht direkt über zu Phase 2. Ein kaputtes Reasoning-Panel sollte den User niemals seine Antwort kosten.

Phase 2 — Agent mit Tools

Phase 2 baut einen frischen Strands Agent pro Request auf — kein geteilter veränderlicher Zustand zwischen gleichzeitigen Chats —, stellt die Konversationshistorie der Session darin wieder her und führt die Tool-Loop mit sechs registrierten Tools aus:

Tool	Zweck
`search_knowledge_base(query)`	Hybride FAISS + BM25 Suche, Top-7, RRF Fusion. Scope-Filter-aware.
`list_documents()`	Bestandsaufnahme jeder indizierten Datei mit Typ und Chunk-Anzahl.
`analyze_document(filename)`	Innerer Gemma-Aufruf → strukturierte Zusammenfassung (Themen, Entitäten, Fakten).
`compare_documents(doc_a, doc_b, question)`	Innerer Gemma-Aufruf, der dokumentübergreifend antwortet.
`calculator(expression)`	Sicherer AST-Evaluator — kein `eval()`, kein beliebiger Code.
`current_time()`	Zeitstempel für zeitbewusste Fragen.

Der Agent entscheidet, welche Tools er in welcher Reihenfolge aufruft. Es gibt keinen hart codierten Router; der System-Prompt erklärt, was verfügbar ist, und Strands kümmert sich um die Schleife. Für die meisten Dokumentenfragen ist der Weg: search_knowledge_base → Antwort. Für Vergleiche: compare_documents → Antwort. Für “Welche Dateien habe ich?”: list_documents → Antwort. Für Begrüßungen und einfache Mathematik sagt der System-Prompt dem Agenten, dass er die Suche komplett überspringen darf. Das Modell wählt selbst.

Zwei Details, deren Debugging Zeit gekostet hat, um sie richtig hinzubekommen:

Phase 2 läuft mit explizit deaktiviertem Thinking. Ohne dieses Flag kann Gemmas Standardverhalten <think>…</think>-Tags in die sichtbare Antwort durchsickern lassen, und alles vor dem schließenden Tag wird vom Markdown-Renderer verschluckt. Eine Modelloption — options={"thinking": False} — behob einen Bug mit “abgeschnittenen Antworten”, der viel unheimlicher aussah, als er tatsächlich war.
Zitate werden vor dem ersten Antwort-Token rausgeschrieben. Tools laufen, bevor die Text-Deltas ankommen. Bis das erste sichtbare Token gestreamt wird, ist also jede Quelle, die die Suche gefunden hat, bereits in der Sidebar. Der Accumulator ist ein Request-lokaler ContextVar, an den das Such-Tool anhängt.

# Simplified — the real loop reads Strands' raw event dicts
async for event in agent.stream_async(user_input):
 delta = event["event"].get("contentBlockDelta", {}).get("delta", {}).get("text")
 if delta:
 for doc in new_citations(): # drain the ContextVar accumulator
 yield envelope("metadata", doc)
 yield envelope("text", delta)

Warum das wichtiger ist, als es klingt

Du könntest ähnliches Verhalten mit einem einzigen Agenten-Aufruf implementieren, der thinking-Events mit text-Events verschränkt. Die Gründe, warum ich es trotzdem aufgeteilt habe:

Das Thinking-Modell und das Tool-Modell können unterschiedlich sein. Aktuell sind beide gemma4:e4b, aber die Architektur erlaubt es mir, ein kleineres, schnelleres Modell für das Reasoning in Phase 1 auszutauschen und das große für die Tool-Nutzung in Phase 2 zu behalten. Das mache ich noch nicht — aber ich will die Option haben.
Phase 1 streamt immer sofort. Eine reine Agenten-Loop fängt erst an, Tokens zu produzieren, nachdem das Modell entschieden hat, was es sagen will. Das Zwei-Phasen-Modell garantiert, dass der User fast sofort nach Drücken der Enter-Taste eine Aktivität sieht, unabhängig davon, wie komplex die Tool-Arbeit in Phase 2 wird.
Fehler sind isoliert. Wenn Phase 2 umfällt (Ollama Timeout, Tool Error), ist die Argumentation aus Phase 1 immer noch sichtbar — der User kann sehen, was das Modell tun wollte, was den Fehler deutlich weniger frustrierend macht als ein blankes “irgendwas ist schiefgelaufen”.

ContextVar-Isolation, noch einmal

Der gleiche ContextVar-Trick, der im das Retrieval eingegrenzt hat, greift auch hier. Zu Beginn jedes /rag-Streams setzt der Handler zwei Request-lokale Variablen: den Dokument-Scope-Filter und den Zitier-Accumulator. Die Tools des Agenten lesen und schreiben diese implizit. Die Konversationshistorie selbst lebt in einem Per-Session-Store, der durch Per-Session asyncio-Locks geschützt ist. Zwei gleichzeitige Requests im selben Chat können sich also auch nicht gegenseitig korrumpieren.

Getestet mit zwei offenen Browser-Tabs im selben Backend, mit Scope auf verschiedene Dokumentenkategorien, in denen gleichzeitig überlappende Queries gesendet wurden. Null Kreuzkontamination. Die Test-Suite deckt dies explizit in test_thinking.py und test_doc_scope_filter.py ab — schau dir den für die ganze Geschichte an.

Die Frontend-Seite des Vertrags

Ein Detail, das mich ins Straucheln gebracht hat: Das ist ein POST-Endpoint, also scheidet die EventSource-API des Browsers (die nur GET macht) aus. Das Frontend nutzt fetch und liest den Response-Body inkrementell aus, splittet bei Newlines und parst jede Zeile als JSON:

// Simplified from useRagStream.ts
const res = await fetch("/rag", {
 method: "POST",
 body: JSON.stringify(payload),
});
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
 const { done, value } = await reader.read();
 if (done) break;
 buffer += decoder.decode(value, { stream: true });
 const lines = buffer.split("\n");
 buffer = lines.pop()!; // keep the trailing partial line
 for (const line of lines) {
 if (!line.trim()) continue;
 const { type, data } = JSON.parse(line);
 switch (type) {
 case "thinking":
 appendThinking(data);
 break;
 case "text":
 appendText(data);
 break;
 case "metadata":
 addCitation(data);
 break;
 case "memory":
 updateMemoryMeter(data);
 break;
 }
 }
}

Das Reasoning-Panel startet zusammengeklappt, mit einem kleinen pulsierenden Indikator, solange die Thinking-Tokens noch streamen — genug, um zu signalisieren “das Modell arbeitet”, ohne dem User gleich eine Wand aus Chain-of-Thought ins Gesicht zu drücken. Ein Klick klappt den vollen Text aus, während oder nach dem Stream.

Was ich mir noch mal ansehen würde

Phase 1 denkt auf eine volle Antwort hin, und wir werfen den Antwortteil weg. Ein eigener “Plane dein Vorgehen, aber antworte noch nicht”-Prompt für Phase 1 würde den Argumentationsstrang kompakter und billiger machen. Heute teilt er sich den Haupt-System-Prompt — das ist simpler, aber die Argumentation kann abschweifen.
Noch kein Interrupt. Sobald Phase 1 startet, läuft sie bis zum Ende durch. Wenn der User mitten im Stream eine Nachfrage tippt, lassen wir sie zu Ende laufen. Ein echter Cancel-Button würde bedeuten, ein Abort-Signal durch Ollamas HTTP-Client zu fädeln — machbar, aber noch nicht gemacht.
Phase 1 denkt manchmal zu viel nach. Begrüßungen und triviale Fragen produzieren immer noch einen Absatz an Begründung. Ein “Sollte ich nachdenken?"-Gate (wahrscheinlich ein winziger Classifier oder einfach eine Heuristik basierend auf der Query-Länge) würde Phase 1 in diesen Fällen komplett überspringen.

Takeaway

Streaming ist nicht einfach nur eine Optimierung. Es ist ein UX-Primitiv. Zwei-Phasen-Streaming kauft dir eine Eigenschaft gratis ein: Der sichtbare Teil der Interaktion startet, bevor der langsame Teil beginnt. Der User darf dem Modell beim Denken zusehen, was — ehrlich gesagt — interessanter ist, als einem Spinner zuzuschauen.

Wenn sich deine Agenten-App langsam anfühlt, obwohl die Antworten schnell kommen, schau dir an, wann die Tokens anfangen zu fließen. Der Fix ist oft nicht ein schnelleres Modell.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
NDJSON	Newline-Delimited JSON	Ein Stream, in dem jede Zeile ihr eigenes komplettes JSON-Objekt ist — das, was `/rag` ausgibt
JSON	JavaScript Object Notation	Das universelle Textformat für strukturierte Daten
UX	User Experience	Wie sich das Produkt in der Nutzung anfühlt — der eigentliche Profiteur vom Zwei-Phasen-Streaming
UI	User Interface	Die sichtbare Oberfläche, in die der Stream rendert
FAISS	Facebook AI Similarity Search	Die dichte (dense) Hälfte des hybriden Retrievals (vorheriger Post)
BM25	Best Match 25	Die Keyword-Hälfte des hybriden Retrievals (vorheriger Post)
RRF	Reciprocal Rank Fusion	Die Rank-only-Formel, die die beiden Ergebnislisten zusammenführt
AST	Abstract Syntax Tree	Die geparste Form eines Ausdrucks — wie der Taschenrechner Mathe ohne `eval()` berechnet
HTTP	HyperText Transfer Protocol	Das Protokoll, das den Stream transportiert
SSE	Server-Sent Events	Das eingebaute GET-only Streaming-Format des Browsers — hier nicht nutzbar, weil `/rag` ein POST ist
API	Application Programming Interface	Die Grenze, die das Frontend aufruft

Als Nächstes: — wie CogniVault bearbeitete PDFs neu einliest, ohne alles neu zu embedden, und ein kill -9 mitten in der Pipeline überlebt.

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