System Design |

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

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

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

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

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

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

Das GPU-Passthrough-Problem

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

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

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

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

Die Brückenlösung

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

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

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

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

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

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

Was ist mit der Vektor-Datenbank?

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

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

Erlebe es in Aktion

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

Hol dir den Code:
Schau dir das Walkthrough an:

Anhang: Abkürzungen in diesem Beitrag

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

Teil 2 · CogniVault Architektur: Dauerhafte Ingestion mit DBOS

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

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

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

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

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

Das Fabrikbuch (DBOS)

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

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

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

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

SHA-256 Hashing: Der Idempotenz-Trick

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

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

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

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

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

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

Was kommt als Nächstes?

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

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

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

Anhang: Abkürzungen in diesem Beitrag

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

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

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

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

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

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

Zwei Wege, ein Buch zu finden

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

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

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

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

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

Der Agent entscheidet, wann gesucht wird

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

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

Hier ist die Blaupause der Architektur dieses Loops:

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

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

Was kommt als Nächstes?

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

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

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

Anhang: Abkürzungen in diesem Beitrag

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