Schema-Weiterentwicklung und Abwärtskompatibilität

Extraktionsschemas sind nicht statisch. Geschäftsanforderungen entwickeln sich weiter, neue Dokumenttypen kommen hinzu, und Sie entdecken Felder, die Sie von Anfang an hätten erfassen sollen. Das Ändern eines Schemas in einer aktiven Pipeline führt zu einem Abwärtskompatibilitätsproblem: Bereits extrahierte Datensätze verwenden das alte Schema, während neue Datensätze das neue verwenden. Diese Umstellung sicher zu verwalten, ist der Kern der Schemaentwicklung.

Weisen Sie jedem Schema eine Versionsnummer zu und speichern Sie diese zusammen mit jedem extrahierten Datensatz. Erhöhen Sie die Version, wenn Sie das Schema ändern. So können Sie Datensätze nach Schema-Version abfragen, Migrationen für alte Datensätze ausführen und für jede Version eine separate Validierungslogik beibehalten. Ein einfaches Zeichenkettenfeld schema_version in jedem Ausgabemodell ist ausreichend.

Additive Änderungen sind sicher: Das Hinzufügen eines Optional-Felds oder eines Felds mit Standardwert beschädigt weder alten Extraktionscode noch alte Datensätze. Nicht abwärtskompatible Änderungen sind riskant: Das Umbenennen eines Felds, die Änderung eines Typs von string zu int oder das Entfernen eines Felds beschädigt nachgelagerte Verbraucher. Bevorzugen Sie immer additive Änderungen. Wenn eine nicht abwärtskompatible Änderung unvermeidbar ist, erstellen Sie eine neue Major-Schema-Version und führen Sie die Migration kontrolliert durch.

Nehmen Sie die Schema-Version in Ihre Tabelle mit den Extraktionsergebnissen auf, damit Sie immer wissen, welche Version den jeweiligen Datensatz erzeugt hat. Eine häufige Vorgehensweise ist eine jsonb-Spalte mit den vollständigen extrahierten Daten sowie eine Textspalte schema_version. So können Sie versionsabhängige Abfragen schreiben und ältere Datensätze gezielt in Zeitfenstern mit geringem Datenverkehr migrieren.

Schreiben Sie für jeden Übergang zwischen Schema-Versionen ein Migrationsskript, das alte Datensätze liest, in das neue Format umwandelt und mit der neuen Version zurückschreibt. Führen Sie Migrationen in kleinen Batches mit Transaktionen aus, damit ein Fehler die Datenbank nicht in einem teilweise migrierten Zustand hinterlässt. Halten Sie das alte Schema immer verfügbar, bis die Migration nachweislich abgeschlossen ist.

Führen Sie während einer Schema-Migration eine parallele Validierung durch: Extrahieren Sie für eine Stichprobe eingehender Dokumente gleichzeitig mit dem alten und dem neuen Schema. Vergleichen Sie die Ergebnisse, um zu überprüfen, dass das neue Schema alles erfasst, was das alte erfasst hat, und zusätzlich die neuen Felder. Deaktivieren Sie das alte Schema erst, wenn die parallele Validierung bei einer statistisch signifikanten Stichprobe eine stabile Übereinstimmung zeigt.

Verwenden Sie Feature Flags, um zu steuern, wann Ihre Pipeline vom alten auf das neue Schema umschaltet. So können Sie das neue Schema schrittweise für einen Prozentsatz des Datenverkehrs einführen, Fehlerraten überwachen und bei Problemen sofort zurücksetzen – ohne den Code erneut bereitzustellen. Sowohl Dienste wie LaunchDarkly als auch eine einfache Datenbankzeile eignen sich dafür.

Nachgelagerte Verbraucher, die extrahierte Daten lesen, müssen mehrere Schema-Versionen zuverlässig verarbeiten können. Verwenden Sie in Ihrem Verbrauchercode eine discriminated union, die anhand des Felds schema_version die passende Parsing-Logik auswählt. Das ist robuster als bedingte if-else-Ketten und lässt sich leichter erweitern, wenn Version 3 hinzukommt.

Führen Sie ein neues Schema vor der Bereitstellung mit Ihrem gesamten Regressionstestsatz aus: einer kuratierten Sammlung repräsentativer Dokumente mit bekannten erwarteten Ausgaben. Vergleichen Sie die F1-Scores für jedes Feld zwischen dem alten und dem neuen Schema. Eine Verschlechterung des F1-Scores für ein beliebiges Feld bedeutet, dass die Beschreibung des neuen Schemas das Modell verwirrt hat – korrigieren Sie die Feldbeschreibung vor der Veröffentlichung.

Sobald eine Schema-Version nicht mehr für neue Extraktionen verwendet wird, können Sie sie als veraltet kennzeichnen. Das bedeutet: Keine neuen Datensätze mehr in dieser Version akzeptieren, alte Datensätze lesbar halten und einen Termin für die Ablösung festlegen, an dem alte Datensätze migriert oder archiviert werden. Dokumentieren Sie die Ablösung in einem Changelog, damit alle Verbraucher wissen, dass sie ihren Parsing-Code aktualisieren müssen.

Jede Schemaänderung muss von einem Changelog-Eintrag begleitet werden, der beschreibt, was geändert wurde, warum die Änderung vorgenommen wurde, wie die Migration funktioniert und welche Auswirkungen zu erwarten sind. Teilen Sie Changelog-Einträge vor der Bereitstellung der Änderung mit allen Teams, die die extrahierten Daten verwenden. Viele Katastrophen bei Schema-Migrationen entstehen nicht durch technische Fehler, sondern durch Verbraucher, die nicht über eine bevorstehende Änderung informiert wurden.

Testen Sie Ihr Verständnis der Schemaentwicklung und Abwärtskompatibilität in Extraktionspipelines.

In dieser Lektion haben Sie Folgendes gelernt: Schema-Versionierung speichert neben jedem extrahierten Datensatz eine Versionskennung, sodass Sie gezielt migrieren können, additive Änderungen sind sicher, während das Umbenennen oder Ändern von Feldtypen eine sorgfältige Migration erfordert, und die parallele Validierung ermöglicht es Ihnen, das neue Schema zu überprüfen, bevor Sie das alte außer Betrieb nehmen. Als Nächstes messen wir die LLM-Latenz mit den Metriken TTFT und TPOT.