AI |

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 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 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

AI |

Gemma CogniVault

Überblick

Was drinsteckt

Vier Bereiche

Highlights

Darüber schreiben

Probier es aus

Teil 8 · Eine lokale KI-App testen: 351 Tests, Null Infrastruktur

Die 22 Testdateien

Was gemockt wird, was nicht

Ollama mocken

DBOS mocken

Echtes SQLite, mit einem Override

Das TestClient-Pattern

Lücken in der Abdeckung, die ich akzeptiere

Wofür die Suite eigentlich da ist

Was sich zum Ausborgen lohnt

Anhang: Abkürzungen in diesem Post

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

Das Muster

Schritt 3: format="json" leistet echte Arbeit

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

Schritt 4: Tolerant parsen

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

Schritt 6: Die Outline darf es einmal neu versuchen

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

Was ich bisher beim Bauen dieser Generatoren gelernt habe

Anhang: Abkürzungen in diesem Beitrag

Teil 3 · Zwei-Phasen-Streaming: Zeigen, wie das Modell denkt, bevor es handelt

Die Struktur

Phase 1 — Nur Nachdenken

Phase 2 — Agent mit Tools

Warum das wichtiger ist, als es klingt

ContextVar-Isolation, noch einmal

Die Frontend-Seite des Vertrags

Was ich mir noch mal ansehen würde

Takeaway

Anhang: Abkürzungen in diesem Post

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

Zwei Arten von “ähnlich”

Der Stack

Warum FAISS IndexFlatIP und nicht HNSW oder IVF?

Reciprocal Rank Fusion

Scope-Filterung mit ContextVar-Isolierung

Chunking-Entscheidungen, die sich später auszahlen

Was ich anders machen würde

Fazit

Anhang: Abkürzungen in diesem Beitrag

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

Die undichte Abstraktion

Was “Local-First” hier tatsächlich bedeutet

Was du dafür bekommst

Der Aufbau der App

Was als Nächstes kommt

Anhang: Abkürzungen in diesem Post

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

Warum FAISS `IndexFlatIP` und nicht HNSW oder IVF?