FastAPI |

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.

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