Ollama |

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