PostgreSQL |

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 4 · Crash-Resumable Ingestion: DBOS, SHA-256 und wie man ein kill -9 überlebt

Tue, 05 May 2026 00:00:00 +0000

Teil einer Serie über den Bau von . Zuvor: .

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

Es gibt zwei Dinge, die deine RAG-Ingestion-Pipeline auf keinen Fall tun sollte:

Ein 200-seitiges PDF neu einbetten, weil du einen Tippfehler auf Seite 12 korrigiert hast.
Ihren Fortschritt verlieren, wenn du auf halber Strecke den Laptop zuklappst.

Das Erste verschwendet Zeit und Rechenressourcen. Das Zweite führt zu Misstrauen in das System. Beides hat denselben Ursprung: Die Ingestion wird wie eine Fire-and-Forget-Funktion behandelt, obwohl sie eigentlich eine lang laufende Pipeline ist, deren Zwischenzustände es wert sind, erhalten zu bleiben.

CogniVault behandelt Ingestion als einen Durable Workflow. Genauer gesagt als einen -Workflow, der in Postgres mit Checkpoints versehen ist und Content-Hashing für inkrementelle Arbeit nutzt. In diesem Beitrag schauen wir uns beides an.

Die Pipeline

1. Scan docs/ → SHA-256 hash per file
 ├── New file → queue for embedding
 ├── Changed file → soft-delete old chunks, re-embed
 └── Unchanged → skip (idempotent)

2. Extract text → per-format extractor (PDF/OCR, DOCX, PPTX, XLSX, MD, CSV, TXT, HTML)
3. Chunk → RecursiveCharacterTextSplitter (1000 chars, 100 overlap)
4. Embed → embeddinggemma via Ollama, batches of 5
5. Save → append to FAISS IndexFlatIP + JSON metadata on disk

Die rechenintensiven Stufen laufen als DBOS-Schritte innerhalb eines übergeordneten Workflows und sind alle mit Checkpoints versehen: Wenn der Prozess zwischen den Schritten stirbt, macht der nächste Start genau beim letzten abgeschlossenen Schritt weiter.

SHA-256 als einzige Quelle der Wahrheit

Der naive Ansatz ist, die Ingestion anhand des Dateinamens zu verfolgen. Das geht genau dann schief, wenn jemand eine Datei direkt bearbeitet. Der Dateiname ist derselbe; der Inhalt nicht. Der Vector-Store schleppt dann klammheimlich veraltete Chunks mit sich herum.

Die Lösung ist inhaltsadressiert: Hashe die Datei-Bytes und speichere den Hash zusammen mit den Chunks. Bei jedem Ingestion-Durchlauf passiert Folgendes:

current_hash = hashlib.sha256(file_bytes).hexdigest()
stored_hash = chunk_metadata_for(filename).get("file_hash")

if stored_hash is None:
 schedule_ingest(filename) # new file
elif stored_hash == current_hash:
 skip(filename) # unchanged
else:
 soft_delete_chunks_for(filename) # changed
 schedule_ingest(filename)

Das verleiht der Ingestion eine idempotente Eigenschaft, die Gold wert ist: Die Pipeline zweimal hintereinander laufen zu lassen, bewirkt beim zweiten Mal fast nichts. Das ist nicht nur eine Optimierung — erst dadurch wird der nächste Abschnitt überhaupt möglich.

DBOS-Workflows

ist eine Python-Bibliothek, die normale Funktionen in Checkpoint-basierte Workflows verwandelt, die von Postgres gestützt werden. Das Modell ist kinderleicht: Dekoriere eine Funktion mit @DBOS.workflow(), markiere jeden lang laufenden Aufruf darin als @DBOS.step(), und DBOS speichert während der Ausführung für jeden Schritt Input, Output und Status in Postgres.

Wenn der Workflow abstürzt — Prozess gekillt, OS-Reboot, Abbruch der Postgres-Verbindung — sieht der nächste Start, dass ein unvollendeter Workflow mit derselben ID existiert, spielt die aufgezeichneten Schritt-Outputs aus Postgres ab (ohne sie neu auszuführen) und macht beim ersten unvollständigen Schritt weiter.

Hier ist die eigentliche Schrittstruktur (leicht vereinfacht aus backend/services/ingest.py):

@DBOS.workflow()
def ingest_workflow() -> int:
 filenames = list_document_files() # @DBOS.step — scan + hash check
 docs = []
 for name in filenames:
 docs += process_single_document(name) # @DBOS.step — extract text, one file each
 chunks = chunk(docs) # plain Python — fast, re-runs freely
 embeddings = []
 for batch in batches_of_5(chunks):
 embeddings += embed_batch(batch) # @DBOS.step — the slow one, retried on failure
 save_vector_store(embeddings, chunks) # @DBOS.step — append to FAISS + metadata
 return len(chunks)

Die Granularität von @DBOS.step entspricht der Granularität der Crash-Recovery und wurde bewusst so gewählt. Die Extraktion ist ein Schritt pro Datei, sodass bei einem Absturz während Datei 9 von 10 die ersten acht nicht neu gelesen werden. Embedding ist ein Schritt pro Batch von fünf Chunks, und zwar aus einem bestimmten Grund: embed_batch ist der langsame Part. Wenn der Laptop während der Embeddings den Geist aufgibt, setzen wir den Embedding-Loop beim fehlgeschlagenen Batch fort, nicht bei der PDF-Extraktion.

Fällt dir auf, was kein Schritt ist? Das Chunking. Text aufzuteilen ist schnelle, reine Python-Arbeit — es mit Checkpoints zu versehen, würde mehr Buchhaltung im Ledger kosten, als es bei einer Fortsetzung einfach neu zu machen.

In der Batch-Größe verbirgt sich noch ein kleiner Trick. DBOS speichert den Output jedes Schritts in Postgres, und embed_batch gibt seine Vektoren zurück — also enthält jeder Ledger-Eintrag Float-Werte für fünf Embeddings. Kleine Batches halten jeden Checkpoint-Datensatz klein und jeden erneuten Versuch (Retry) günstig. Ein riesiger “Bette alles ein”-Schritt würde eine riesige Ledger-Zeile und null Resume-Granularität bedeuten.

Die Format-Extraktoren

Schritt 2 (process_single_document) ist eine Weiche basierend auf der Dateiendung. Jeder Extraktor ist klein und einleuchtend; die interessanten Entscheidungen liegen in der Chunking-Strategie, die jeder nachgelagert füttert.

Format	Library	Chunking note
PDF	`pypdf` Seite für Seite; `pytesseract` OCR-Fallback für Bild-Seiten	Rekursiver Splitter, 1000/100
DOCX	`python-docx` (Absätze + Tabellenzeilen als Text verbunden)	Rekursiver Splitter
PPTX	`python-pptx`	Ein Chunk pro Folie (Titel + Body-Text)
XLSX	`openpyxl`	Header + 20-Zeilen-Batches, pro Arbeitsblatt
MD	`MarkdownHeaderTextSplitter`	Ein Chunk pro H1/H2/H3-Abschnitt, Breadcrumbs davor
CSV	Manueller Reader	Header-Zeile + 20-Zeilen-Batches
TXT	Rohes UTF-8 Lesen	Rekursiver Splitter
HTML	`trafilatura` sauberer Text	Rekursiver Splitter

Der OCR-Fallback ist es wert, kurz innezuhalten. PDFs gibt es in zwei Ausführungen: solche mit einer echten Textebene und solche, die im Grunde nur gescannte Bilder in einem PDF-Kostüm sind. pypdf liefert für die zweite Sorte nichts Brauchbares zurück, wirft aber auch keinen Fehler — es gibt einfach leere Strings zurück. Ohne ein Fallback lügt dich dein “Ingestion erfolgreich”-Log an.

Der Detektor ist eine Heuristik: Wenn pypdf weniger als 50 Zeichen für eine Seite zurückgibt, leite die Seite durch pymupdf → Pillow → pytesseract OCR. Langsamer, aber es produziert immerhin Text. Der Schwellenwert ist so eingestellt, dass er sensibel genug ist, um gescannte Seiten abzufangen, ohne legitimerweise kurze Seiten (wie ein Kapitel-Deckblatt oder ein Impressum) zu bestrafen.

Soft Delete, nicht Hard Delete

Wenn sich eine Datei ändert und wir sie neu einlesen, müssen die alten Chunks weg. Es ist verlockend, sie physisch aus dem FAISS-Index zu entfernen, aber FAISS IndexFlatIP unterstützt kein effizientes Löschen — du müsstest ihn neu aufbauen.

Stattdessen Soft Delete: Bei geänderten Dateien werden die alten Chunks in den Metadaten mit einem deleted: true-Flag markiert; neue Chunks werden ohne Flag angehängt. Bei einer Suchanfrage wird nach diesem Flag gefiltert, sodass veraltete Vektoren völlig harmlos im Index liegen bleiben. Wenn sich jemals genug totes Gewicht ansammelt, ist das Ventil offensichtlich — bau den Index nur mit aktiven Chunks neu auf —, aber in der Praxis habe ich das noch nie gebraucht.

Das ist dasselbe Muster, das die meisten Append-only-Systeme verwenden. Es passt natürlich perfekt zum Content-Hashing — Markieren-und-Anhängen ist viel billiger als Entfernen-und-Neubauen. Eine Feinheit dabei: Der Keyword-Index muss mitziehen. CogniVaults VectorDB.delete_by_source() setzt die Flags und baut BM25 neu auf, und zwar über die verbleibenden aktiven Chunks, sodass sich die beiden Retriever nie uneinig darüber sind, was eigentlich existiert.

Was der User sieht

Das Starten einer Ingestion (POST /ingest) liefert eine workflow_id zurück, und das Frontend fragt regelmäßig GET /ingest/status/{workflow_id} ab, um eine Live-Timeline der Workflow-Schritte zu zeichnen — Scannen, Extraktion pro Datei (“Lese Seiten… 3 von 21”), Einbetten (“Kalibriere Batch 4 von 12”), Speichern. Wenn der User den Tab mitten in der Ingestion schließt, fünf Minuten später wiederkommt und ihn neu öffnet — der Workflow ist im Hintergrund sowieso fertig gelaufen. Der nächste Aufruf von GET /api/vault/stats spiegelt die neue Chunk-Anzahl wider. Kein “Klicken zum Fortsetzen”-Button, kein manueller Recovery-Tanz.

Als ich das erste Mal mitten im Einbetten den Deckel zugeklappt habe und dann beim Aufwecken zusehen konnte, wie der Workflow sich den nächsten Schritt geschnappt und einfach weitergemacht hat, war ich, ehrlich gesagt, ein bisschen stolz. Das ist genau die Eigenschaft, die ich wollte, und das mit überraschend wenig Code.

Fallstricke und Randfälle

Ein paar Dinge, die ich auf die harte Tour lernen musste:

Mach embed_batch nicht zu groß. Ollama ist nicht besonders gut im Umgang mit Backpressure. Batches von 5 sind ein Sweetspot für embeddinggemma auf einer Maschine mit 16 GB RAM — größere Batches bleiben am Speicher hängen, kleinere verschwenden Overhead für die Round-Trips. (Und wie oben erwähnt: Die Batch-Größe bestimmt gleichzeitig die Größe deines Checkpoint-Datensatzes.)
Sei vorsichtig beim Löschen von Dateien. Soft-gelöschte Chunks müssen auch aus dem Korpus von BM25 verschwinden, sonst liefert die Keyword-Suche weiterhin Text, den die Dense Search (Vektorsuche) gar nicht mehr sieht. Wenn du BM25 innerhalb von delete_by_source() neu aufbaust, bleiben die beiden im Gleichschritt.
OCR ist langsam. Ein 50-seitiger Scan kann eine Minute oder länger dauern. Mach diese Wartezeit für den User sichtbar, sonst denken sie, das System hat sich aufgehängt.

Fazit

Durable Workflows sind nicht nur etwas für verteilte Systeme. Eine lokale App für einen einzelnen Nutzer profitiert davon auf genau die gleiche Weise: inkrementelle Arbeit, Crash-Recovery, idempotente Retries. DBOS macht die Einstiegskosten dafür extrem niedrig — dekoriere deine Funktion, lass Postgres lokal laufen, und du bekommst eine Pipeline, die das Zuklappen des Laptops, OS-Updates und dein eigenes Ctrl-C überlebt.

In Kombination mit inhaltsadressiertem Hashing ist die Ingestion nicht länger etwas, das du meidest, aus Angst, 20 Minuten warten zu müssen. Es wird zu etwas, das du einfach neu startest, wann immer du Lust dazu hast — denn ein Neustart kostet nichts, wenn sich nichts geändert hat.

Anhang: Abkürzungen in diesem Beitrag

Abbreviation	Full form	Meaning
DBOS	Database-Oriented Operating System	Eine Bibliothek, die Workflow-Schritte in Postgres sichert, sodass abgestürzte Jobs fortgesetzt statt neu gestartet werden
SHA-256	Secure Hash Algorithm, 256-bit	Ein Content-Fingerabdruck: Änderst du ein Byte einer Datei, ändert sich der Hash komplett
RAG	Retrieval-Augmented Generation	Rufe zuerst relevante Passagen aus deinen eigenen Dokumenten ab; lass das Modell daraus antworten
OCR	Optical Character Recognition	Das Umwandeln von Bildern von Text (gescannte Seiten) in maschinenlesbaren Text
FAISS	Facebook AI Similarity Search	Der Vektorindex, an den die Embeddings angehängt werden
IP (in `IndexFlatIP`)	Inner Product	FAISS’s Ähnlichkeitsmaß; entspricht der Cosinus-Ähnlichkeit bei normalisierten Vektoren
BM25	Best Match 25	Der Keyword-Index, der beim Löschen mit FAISS im Gleichschritt bleiben muss
PDF / DOCX / PPTX / XLSX / MD / CSV / TXT / HTML	Portable Document Format / Word / PowerPoint / Excel / Markdown / Comma-Separated Values / plain text / HyperText Markup Language	Die Formate, die von den entsprechenden Extraktoren verarbeitet werden
JSON	JavaScript Object Notation	Das Format der Chunk-Metadaten-Datei neben dem FAISS-Index
UTF-8	Unicode Transformation Format, 8-bit	Die Textkodierung, die beim Lesen von Klartextdateien verwendet wird
OS	Operating System	Das, was mitten in der Ingestion unter dir neu startet

Als Nächstes: — was passiert, wenn Gemma 4 enthusiastisch {"questions": [{"text": "..."},}] zurückgibt.