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

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 Source Code nachprüfen. Falls du meine Architektur-Deep-Dives 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: Why I Built a Local-First RAG.)

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: Why We Keep Ollama Out of Docker.)

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 CogniVault Source Code ü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: Teil 2 · Von der Datei zum durchsuchbaren Wissen — 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.

No results found