Reliability |

Teil 5 · Zuverlässiges JSON aus einem lokalen LLM bekommen

Sun, 10 May 2026 00:00:00 +0000

Teil einer Serie über die Entwicklung von . Zuvor: .

Alle Abkürzungen werden im Anhang unten auf der Seite vollständig erklärt.

Der Study Hub von CogniVault generiert aus deinen Dokumenten vier Arten von strukturierten Artefakten: Quizzes, mehrteilige Workshops, Flashcard-Decks und Mindmaps. Alle vier benötigen ein Modell, das strukturiertes JSON zurückgibt, keinen Fließtext. Alle vier laufen auf Gemma 4, das lokal über Ollama ausgeführt wird. Und alle vier würden viel zu oft scheitern, wenn ich darauf vertrauen würde, dass das Modell “einfach JSON zurückgibt”.

Hier ist das defensive Muster, das diese Ausfallrate auf nahe null drückt – und was man mit den Fällen macht, die trotzdem noch durchrutschen.

Das Muster

1. Retrieve → hybrid search restricted by user-selected scope
2. Prompt → strict schema-by-example with explicit count + shape rules
3. Generate → ollama.chat with format="json" (grammar-constrained)
4. Parse → json.loads, tolerant of object / array / fenced shapes,
 with a trailing-comma repair pass
5. Validate → drop malformed items rather than fail the whole batch
6. Retry → the workshop outline retries once with a stronger prompt
7. Persist → SQLite (progress.db) so the user can come back later

Jeder Generator in CogniVault folgt diesem Ablauf. Die interessanten Schritte sind 2, 4 und 5.

Schritt 3: `format="json"` leistet echte Arbeit

Ollama bietet eine format="json"-Option, die dem Modell während des Samplings einen Grammatik-Constraint (Einschränkung) auferlegt. Der Decoder gibt keine Tokens aus, die die Ausgabe zu ungültigem JSON machen würden. Das ist nicht perfekt – Schemata umfassen mehr als nur “gültiges JSON”, und das Modell kann immer noch wohlgeformten Müll produzieren – aber es eliminiert die gesamte Klasse von “Das Modell hat angefangen, Text vor der schließenden Klammer zu schreiben”-Fehlern.

Wenn dein lokaler LLM-Stack eine Grammatik-Option unterstützt (Ollama, llama.cpp, vLLM usw.), schalte sie ein. Sie ist nicht umsonst (Sampling wird etwas langsamer), aber die Verbesserung bei den Fehlerarten ist enorm. Ohne sie wirst du dein gesamtes Fehlerbudget für abgeschnittene Objekte ausgeben.

Schritt 2: Ein Schema-im-Prompt, an das sich das Modell auch halten kann

format="json" garantiert, dass die Struktur der Ausgabe JSON ist. Es sagt nichts darüber aus, ob das JSON auch zu deinem Domain-Schema passt. Das ist die Aufgabe des Prompts.

Das Muster, das für mich funktioniert: Anstatt ein formales JSON-Schema reinzuwerfen und zu sagen “halte dich daran”, baue ein ausgefülltes Beispiel ein, das dem Modell die exakte Form und explizite Mengenangaben zeigt. Hier ist das Herzstück des echten Quiz-Templates von CogniVault (es liegt als bearbeitbare Markdown-Datei in backend/prompts/quiz.md):

Output ONLY a single JSON object — no prose, no markdown fences,
no text outside the JSON.

NUMBER OF QUESTIONS: EXACTLY $num_questions. This is a hard requirement.

OUTPUT SCHEMA:
{
 "questions": [
 {
 "type": one of [$types_csv],
 "question": the question text (string, no leading numbering),
 "options": array of strings (length 4 for mcq, length 2 for true_false),
 "correct_index": integer index into options (0-based),
 "explanation": 1-2 sentence explanation of the correct answer
 },
 ... exactly $num_questions entries
 ]
}

Ein paar Entscheidungen, die wichtig sind:

Zeig die Form, beschreibe sie nicht. “Jedes Item hat ein type-Feld” wird viel öfter ignoriert als ein wörtliches Beispiel.
Lege die Anzahl fest. “EXACTLY 10” – wiederholt, in Großbuchstaben, als harte Anforderung – ist viel zuverlässiger als “ungefähr 10”.
Verwende Indizes, keine Wiederholungen. Die richtige Antwort ist correct_index, ein Integer, der auf die options verweist – und nicht noch einmal der Antworttext. Wiederholter Text lädt zu Paraphrasierungen ein (“Paris” vs. “Paris, Frankreich”), und dann geht dein Grading-Vergleich kaputt.
Ein Artefakt pro Aufruf. Ich habe versucht, einen kompletten Workshop (Outline + jede Lektion) in einem Aufruf zu generieren. Die Qualität des Modells nimmt rapide ab, je länger die Antwort wird. Die Aufteilung in “Outline zuerst, Lektionen nach Bedarf” ist die weiter unten beschriebene Zwei-Phasen-Strategie.

Schritt 4: Tolerant parsen

Selbst mit format="json" überleben in der Praxis zwei Parsing-Probleme.

Die Struktur-Überraschung. Das hier hat mich in der Produktion erwischt: Ich war davon ausgegangen, dass das Modell ein reines JSON-Array von Fragen zurückgeben würde. Mit format="json" gibt Gemma aber beständig ein Objekt zurück – {"questions": [...]} – und eine Zeit lang hat mein Parser nur das Array akzeptiert. Das Ergebnis: Ein 502-Fehler bei jeder Quiz-Generierung, bis ich es gefunden hatte. Die Lösung ist ein Parser, der dem Modell entgegenkommt:

# Simplified from backend/services/quiz_generator.py
def extract_items(raw: str) -> list | None:
 for candidate in (raw, extract_json_object(raw), extract_json_array(raw)):
 if candidate is None:
 continue
 data = load_json_lenient(candidate)
 if isinstance(data, list):
 return data # bare array
 if isinstance(data, dict):
 items = data.get("questions") # the expected object shape
 if isinstance(items, list):
 return items
 return None

Lexikalische Ausrutscher. Manchmal rutscht ein nachgestelltes Komma durch. Die Reparatur ist absichtlich eng gefasst – ein Regex-Durchlauf, danach aufgeben:

def load_json_lenient(text: str):
 try:
 return json.loads(text)
 except json.JSONDecodeError:
 repaired = re.sub(r",(\s*[\]}])", r"\1", text) # strip trailing commas
 try:
 return json.loads(repaired)
 except json.JSONDecodeError:
 return None

Ich versuche nicht, Klammern auszugleichen, abgeschnittene Strings zu vervollständigen oder fehlende Felder zu erraten. Entweder ist die Ausgabe mit einem Trailing-Comma-Pass und etwas Substring-Extraktion reparierbar, oder eben nicht – und dann gehen wir zu Schritt 5.

Schritt 5: Fehlerhafte Items verwerfen, nicht den ganzen Batch scheitern lassen

Das war die Entscheidung, mit der ich am längsten zu kämpfen hatte, bis ich meinen Frieden damit gemacht habe.

Wenn das Modell 10 Quizfragen zurückgibt, aber bei Nummer 7 das options-Feld fehlt, ist die Versuchung groß, einen Fehler auszuwerfen und den ganzen Batch neu zu generieren. Tu das nicht. Validiere jedes Item einzeln und verwirf diejenigen, die fehlschlagen.

# CogniVault does this with explicit field checks into a dataclass;
# pydantic works just as well.
questions = []
for raw_item in parsed_items:
 q = validate_item(raw_item, allowed_types) # returns None if malformed
 if q is not None:
 questions.append(q)

Der Nutzer bekommt 9 Fragen statt 10. Das fällt ihm nicht auf. Die gesamte Generierung neu zu starten, um Frage 7 zu reparieren, kostet 30 Sekunden und führt vielleicht zu neuen Fehlern in den Fragen 1-6. Der “Dropped-Item”-Ansatz ist für die UX einfach streng genommen besser. (Das Modell schießt übrigens auch manchmal über das Ziel hinaus – die validierte Liste wird dann einfach auf die angeforderte Menge gekürzt.)

Schritt 6: Die Outline darf es einmal neu versuchen

Workshops sind die Ausnahme, die die Regel bestätigt. Ein Workshop ist eine strukturierte Outline (Titel, Zusammenfassung, Lektionsliste) plus der Inhalt jeder Lektion. Die Outline muss parsbar sein – bei einem Inhaltsverzeichnis gibt es keinen Teilerfolg. Deshalb löst ein Parsing-Fehler hier genau einen Retry aus, bei dem der Prompt noch einmal mit einer strengen Erinnerung geschickt wird: “Your previous response was unparseable. Output ONLY a single valid JSON object.” Wenn der zweite Versuch auch fehlschlägt, bekommt der Nutzer eine klare Fehlermeldung mit dem Vorschlag, den Scope etwas einzuengen.

Ein Retry, nicht drei. Drei Retries, wenn das Modell ohnehin verwirrt ist, verschwenden nur Sekunden und Strom.

Die Lektionen selbst sind interessanterweise gar kein JSON. Ein Lektionstext ist Fließtext – ihn in einen JSON-String zu zwingen, brächte nichts und würde nur Escaping-Kopfschmerzen verursachen. Lektionen werden als reines Markdown generiert und durchlaufen dann einen kleinen Cleanup-Pass, die Chat-Floskeln entfernt, die das Modell trotz gegenteiliger Anweisungen manchmal hinzufügt (“I hope this helps!”, “Let me know if…”). Andere Ausgabe, anderer Vertrag.

Zwei-Phasen-Ansatz: Outline zuerst, Lektionen nach Bedarf

Workshops nutzen ein zweistufiges Generierungsmuster:

Pass 1 — generate outline: {"title": ..., "lessons": [{"title": ...}, ...]} (cheap, JSON)
Pass 2 — for each lesson: a full Markdown lesson body (on demand)

Die Outline ist schnell da und lässt den Nutzer sofort die Struktur des Workshops sehen. Jede Lektion wird erst generiert, wenn der Nutzer sie öffnet – was bedeutet, dass der Nutzer gerade Lektion 1 liest, während er noch entscheidet, ob er Lektion 5 überhaupt haben möchte. Die Gesamt-Wartezeit bis zum “ersten nützlichen Inhalt” ist so selbst bei einem Workshop mit 10 Lektionen winzig.

Das ist genau der gleiche architektonische Kniff, den die Chat-Seite mit dem anwendet: Teile eine langsame Operation in einen winzigen schnellen Teil und einen größeren langsamen Teil auf, und gib dem Nutzer den schnellen Teil sofort.

Was ich bisher beim Bauen dieser Generatoren gelernt habe

Ein paar destillierte Prinzipien aus den vier Generatoren:

Nutze die Grammatik-Option in deinem Inference-Stack. Versuch erst gar nicht, JSON aus einem frei formulierenden Decoder herauszulocken.
Nagel jeden Quantifikator im Prompt fest. “Exactly 10”, “exactly 4 options”, “one or two sentences”. Vage Mengenangaben = inkonsistenter Output.
Verlass dich nicht auf die oberste Struktur-Ebene. Grammatik-eingeschränktes Gemma mag Objekte; dein Code erwartet vielleicht Arrays. Akzeptiere beides – der Parser ist billiger, als sich darauf zu verlassen, dass das Modell die erwartete Struktur liefert.
Verwerfen, nicht scheitern lassen. Ein verlustbehafteter Erfolg schlägt spröde Perfektion.
Ein Retry, nie mehr. Wenn zwei Versuche kein gültiges Ergebnis liefern, ist der Prompt falsch, nicht das Modell.
Teile große Generierungen auf. Outline + Lektionen. Skelett + Körper. Zwei kleine Aufrufe schlagen einen großen fast jedes Mal. Und wenn ein Teil der Ausgabe natürlicher Fließtext ist, lass ihn auch Fließtext sein.

Lokale LLMs sind im Jahr 2026 gut genug, dass strukturierte Generierung für Features auf Produktionsniveau wirklich nutzbar ist. Sie sind allerdings nicht so gut, dass du auf das defensive Gerüst verzichten könntest. Das obige Gerüst macht insgesamt vielleicht 80 Zeilen Code in allen vier Generatoren aus, und das ist genau der Unterschied zwischen “Demo-Qualität” und “Ich vertraue dem genug, um es zu shippen.”

Anhang: Abkürzungen in diesem Beitrag

Abkürzung	Vollform	Bedeutung
JSON	JavaScript Object Notation	Das strukturierte Textformat, das die Generatoren produzieren müssen
LLM	Large Language Model	Ein neuronales Netz, das auf großen Textmengen trainiert wurde, um Sprache zu lesen und zu generieren
AI	Artificial Intelligence	Software, die Aufgaben ausführt, für die normalerweise menschliche Intelligenz erforderlich ist
MCQ	Multiple-Choice Question	Eine der zwei Arten von Quizfragen (die andere ist True/False)
UX	User Experience	Warum 9 gültige Fragen besser sind als ein Neu-Generierungs-Fehler
SQLite	(SQL = Structured Query Language)	Die Single-File-Datenbank, in der generierte Artefakte gespeichert werden
DBOS	Database-Oriented Operating System	Die Bibliothek für dauerhafte Workflows aus dem vorherigen Beitrag
HTTP 502	Bad Gateway (HyperText Transfer Protocol status code)	Der Fehler, den mein reiner Array-Parser warf, bis ich Gemmas Objektform akzeptierte

Als Nächstes: — was mich das händische Bauen eines SVG-Radial-Layouts gelehrt hat und warum Version zwei trotzdem React Flow nutzt.

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.

Reliability |

Teil 5 · Zuverlässiges JSON aus einem lokalen LLM bekommen

Das Muster

Schritt 3: format="json" leistet echte Arbeit

Schritt 2: Ein Schema-im-Prompt, an das sich das Modell auch halten kann

Schritt 4: Tolerant parsen

Schritt 5: Fehlerhafte Items verwerfen, nicht den ganzen Batch scheitern lassen

Schritt 6: Die Outline darf es einmal neu versuchen

Zwei-Phasen-Ansatz: Outline zuerst, Lektionen nach Bedarf

Was ich bisher beim Bauen dieser Generatoren gelernt habe

Anhang: Abkürzungen in diesem Beitrag

Teil 4 · Crash-Resumable Ingestion: DBOS, SHA-256 und wie man ein kill -9 überlebt

Die Pipeline

SHA-256 als einzige Quelle der Wahrheit

DBOS-Workflows

Die Format-Extraktoren

Soft Delete, nicht Hard Delete

Was der User sieht

Fallstricke und Randfälle

Fazit

Anhang: Abkürzungen in diesem Beitrag

Schritt 3: `format="json"` leistet echte Arbeit