DBOS |

CogniVault Backend erklärt, Teil 2 · Von der Datei zum durchsuchbaren Wissen

Fri, 12 Jun 2026 00:00:00 +0000

Alle Abkürzungen werden im Anhang am Ende der Seite vollständig erklärt.

Ein LLM kann dein PDF nicht “öffnen”. Dieser Satz überrascht viele Neulinge, also lass uns das kurz sacken lassen: Wenn du in CogniVault mit deinen Dokumenten chattest, fasst das Modell die Originaldateien nie an. Es muss etwas zwischen “Ich habe eine Datei in den Browser gezogen” und “Die KI hat mir gerade Seite 47 zitiert” passieren.

Dieses Etwas nennt man Ingestion (Datenaufnahme), und darum geht es in diesem Teil. In haben wir das große Ganze skizziert; heute zoomen wir in einen bestimmten Bereich – das Fließband, das Dateien in durchsuchbares Wissen verwandelt.

Das Fließband

Stell dir die Ingestion wie ein Fließband mit vier Stationen vor:

Extrahieren: Den Text aus jeder Datei herausholen – auch aus gescannten.
Chunken (Zerlegen): Den Text in Stücke zerschneiden, die klein genug sind, um in einen Prompt zu passen.
Embedden (Einbetten): Jeden Chunk in einen Vektor (eine Liste von Zahlen, die seine Bedeutung einfängt) verwandeln, damit ähnliche Ideen im Vektorraum nah beieinander landen.
Speichern: Vektoren und Metadaten so ablegen, dass sie später durchsucht werden können.

flowchart TD A["Upload
POST /upload
gespeichert in docs/"] --> B subgraph WF["DBOS dauerhafter Workflow"] B["Schritt 1
Welche Dateien haben sich geändert?
SHA-256 Fingerabdrücke"] --> C["Schritt 2
Text extrahieren
pro Format + OCR-Fallback"] C --> D["Chunking
1000 Zeichen, 100 Überlappung"] D --> E["Schritt 3
Embedden
embeddinggemma, 5er-Batches"] E --> F["Schritt 4
Speichern
FAISS Index + Metadaten JSON"] end F --> G["In-Memory Index neu laden
sofort durchsuchbar"]

Ziemlich simpel. Die spannende Ingenieursarbeit steckt in den Fehlerfällen – fangen wir also damit an.

Das Kassenbuch der Fabrik: Warum die Pipeline keine Arbeit verlieren darf

Das Embedden einer großen Bibliothek dauert Minuten. Was passiert, wenn dein Laptop bei Seite 800 eines 1.000-seitigen Handbuchs in den Ruhezustand geht? Bei einem einfachen Python-Skript fängt alles wieder bei Seite 1 an.

CogniVault schreibt die Pipeline stattdessen als einen dauerhaften DBOS-Workflow. Stell dir eine Fabrik vor, in der jede Station einen dauerhaften Stempel in ein Kassenbuch drückt, sobald sie eine Kiste fertiggestellt hat. Fällt der Strom aus, baut niemand fertige Kisten neu zusammen – die Arbeiter lesen das Buch und machen beim ersten ungestempelten Eintrag weiter.

DBOS ist dieses Buch, und PostgreSQL ist das Papier, auf dem es geschrieben steht. Jede Station der Pipeline ist ein mit Checkpoints versehener Schritt; nach einem Neustart liefern abgeschlossene Schritte sofort ihre aufgezeichneten Ergebnisse zurück und die Ausführung geht beim ersten unfertigen Schritt weiter. Ein fehlgeschlagener Embedding-Batch wird einfach nochmal probiert.

Das ist auch der Mechanismus hinter der Live-Fortschrittsanzeige in der UI: Der Start einer Ingestion liefert eine workflow_id zurück, und das Frontend fragt regelmäßig einen Status-Endpoint ab, der meldet, welche Schritte abgeschlossen sind, welche laufen und welche noch warten.

Ich habe einen ausführlichen Deep-Dive über diesen Mechanismus geschrieben – inklusive dessen, was passiert, wenn du den Prozess mitten in der Ingestion mit kill -9 beendest – in .

Fingerabdrücke, kein Blindflug: SHA-256 Änderungserkennung

Deine komplette Bibliothek jedes Mal neu zu embedden, wenn du eine einzige Datei hinzufügst, wäre Verschwendung. Bevor also irgendwelche Arbeit passiert, berechnet die Pipeline für jede Datei einen SHA-256 Hash (einen Inhalts-Fingerabdruck – ändere ein Zeichen in der Datei, und der Fingerabdruck ändert sich komplett) und vergleicht ihn mit dem Fingerabdruck, der bei den vorhandenen Chunks der Datei gespeichert ist:

Noch nie gesehen → einlesen (ingest).
Fingerabdruck hat sich geändert → die alten Chunks werden soft-gelöscht und die Datei wird neu eingelesen.
Fingerabdruck identisch → komplett überspringen.

Warum “soft”-gelöscht? Weil der FAISS-Indextyp, den CogniVault nutzt, keine einzelnen Vektoren entfernen kann. Veraltete Chunks werden in den Metadaten einfach als deleted: true markiert; ihre Vektoren bleiben im Index, aber jede Suche filtert sie heraus. Das ist eine ehrliche, langweilige Lösung – und sie korrumpiert niemals den Index.

Jedes Format kriegt eine Sonderbehandlung

Hier ist ein Detail, das eine Demo von einem Produkt unterscheidet. Eine naive Pipeline extrahiert einfach “den ganzen Text” und macht dann Feierabend. Bei CogniVault bekommt jedes Format einen Extractor, der genau die Struktur beibehält, die das Retrieval später braucht:

Format	Strategie
PDF	Seite für Seite, wobei die Seitenzahlen behalten werden (diese werden später zu Quellenangaben). Jede Seite mit weniger als 50 Zeichen gilt als gescannt und wird an die OCR geschickt
Gescannte Seite	Die Seite wird mit etwa 144 dpi als Bild gerendert, dann extrahiert Tesseract OCR (Optical Character Recognition – Text aus Bildern auslesen) die Wörter
Markdown	Wird an Überschriften aufgeteilt; jeder Abschnitts-Chunk bekommt einen Breadcrumb-Präfix wie `[Section: Intro > Setup]`, damit sein Embedding die Dokumentenhierarchie in sich trägt
CSV	Zeilen werden in 20er-Gruppen gechunkt – und jeder Chunk bekommt die Kopfzeile vorangestellt, sodass das Modell immer die Spaltennamen kennt
Excel	Gleiches Zeilen-Gruppen-Prinzip pro Arbeitsblatt, mit dem Präfix `[Sheet: name]`
PowerPoint	Ein Chunk pro Folie
Word	Absätze plus Tabellenzellen
Webseiten	Werden bei Bedarf abgerufen und auf sauberen Artikeltext reduziert – geschützt durch einen SSRF-Guard (Schutz vor Server-Side Request Forgery: der Server weigert sich, private oder interne Adressen abzurufen)

Frag dich mal, warum das CSV-Detail wichtig ist. Wenn Chunk 14 eines Spreadsheets einfach nur zwanzig nackte Zahlenreihen enthält, wird keine Suche ihn jemals mit der Frage “Wie hoch war das Q3-Budget?” in Verbindung bringen. Stellst du die Kopfzeile voran, weiß der Chunk, dass er Budget-Spalten enthält. Struktur ist der Treibstoff fürs Retrieval.

Chunking: 1.000 Zeichen mit 100 Zeichen Sicherheitsnetz (Überlappung)

Lange Texte werden in Stücke von etwa 1.000 Zeichen zerlegt, wobei sich benachbarte Stücke um 100 Zeichen überlappen. Diese Überlappung ist eine Versicherung: Ein Satz, der genau an der Chunk-Grenze zerschnitten wird, taucht in einem der beiden Nachbarn immer noch als Ganzes auf, sodass keine Idee in die Lücke zwischen den Chunks fällt.

Embedden und Speichern

Chunks werden von embeddinggemma (via Ollama) in 5er-Batches embedded – jeder Chunk wird zu einem Vektor. Die Vektoren werden normalisiert und an einen FAISS-Index angehängt; daneben hält eine JSON-Datei für jeden Chunk den Quelldateinamen, die Seitenzahl, die Kategorie, den Fingerabdruck und den eigentlichen Text fest. Der Index speichert die Zahlen; das JSON speichert die Bedeutung.

Eine Designentscheidung, die man für Anfänger hervorheben sollte: Das hier ist ein exakter Index, kein approximativer. Viele Vektor-Datenbanken nutzen ANN (Approximate Nearest Neighbour)-Abkürzungen, die bei riesiger Skalierung ein wenig Genauigkeit gegen Geschwindigkeit tauschen. Im Maßstab einer persönlichen Bibliothek brauchst du diesen Kompromiss nicht – CogniVault prüft jeden Vektor bei jeder Suche und ist trotzdem schnell.

Die gesamte Reise, von Anfang bis Ende

%%{init: {'sequence': {'actorFontSize': 28, 'messageFontSize': 24, 'loopTextFontSize': 22, 'noteFontSize': 22}}}%% sequenceDiagram actor U as Du participant F as Frontend participant B as FastAPI participant W as DBOS Workflow participant O as Ollama (embeddinggemma) participant V as FAISS + Metadaten U->>F: Drag and Drop einer Datei, Kategorie wählen F->>B: POST /upload B->>B: Typ und Größe validieren, in docs/ speichern F->>B: POST /ingest B->>W: Dauerhaften Workflow starten B-->>F: workflow_id loop Status abfragen F->>B: GET /ingest/status/{workflow_id} B-->>F: Schrittliste (steuert die Fortschrittsanzeige) end W->>W: SHA-256 Änderungserkennung W->>W: Text extrahieren (pro Format, OCR falls gescannt) W->>W: Chunking (1000 Zeichen / 100 Überlappung) W->>O: Embedden in 5er-Batches O-->>W: Vektoren W->>V: Vektoren + Metadaten anhängen B-->>F: SUCCESS — Index neu geladen F-->>U: "Wissens-Sync abgeschlossen"

Fazit

Bei der Ingestion entscheidet sich meistens die eigentliche RAG-Qualität – lange bevor irgendwelches clevere Prompting ins Spiel kommt. Beibehaltene Seitenzahlen, Header, die in jeden Spreadsheet-Chunk kopiert werden, gerettete Scans durch OCR, und ein Kassenbuch, das das Ganze absturzsicher macht: Nichts davon ist glamourös, aber alles davon zeigt sich später in Form von Antworten, die die richtige Seite zitieren.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
LLM	Large Language Model	Ein neuronales Netz, trainiert mit riesigen Textmengen, das Sprache lesen und erzeugen kann
DBOS	Database-Oriented Operating System	Die Bibliothek, die Workflow-Schritte in PostgreSQL sichert, damit abgestürzte Jobs fortgesetzt werden können
SHA-256	Secure Hash Algorithm, 256-bit	Ein Inhalts-Fingerabdruck – ändere ein Byte einer Datei und der Hash ändert sich komplett
OCR	Optical Character Recognition	Text aus Bildern lesen – der Rettungsweg für gescannte PDF-Seiten
SSRF	Server-Side Request Forgery	Ein Angriff, bei dem ein Server ausgetrickst wird, interne URLs abzurufen; der URL-Importer blockiert dies
FAISS	Facebook AI Similarity Search	Der Vektor-Index, an den die Embeddings angehängt werden
ANN	Approximate Nearest Neighbour	Die Genauigkeit-gegen-Geschwindigkeit-Abkürzung, die CogniVault absichtlich nicht nimmt
dpi	Dots Per Inch	Bildauflösung – gescannte Seiten werden vor der OCR mit ca. 144 dpi gerendert
JSON	JavaScript Object Notation	Das Format der Chunk-Metadaten-Datei neben dem FAISS-Index
PDF / CSV	Portable Document Format / Comma-Separated Values	Zwei der acht+ unterstützten Dateiformate
API	Application Programming Interface	Die Endpoints (`/upload`, `/ingest`, `/ingest/status/…`), die den Ablauf steuern

Als Nächstes: — hybrides Retrieval, der 6-Tools-Agent und der 2-Phasen-Stream, der zeigt, wie das Modell denkt, bevor es antwortet.

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.