Schema-evolutie en achterwaartse compatibiliteit

Extractieschema's zijn niet statisch. Zakelijke vereisten veranderen, er verschijnen nieuwe documenttypen en je ontdekt velden die je vanaf het begin had moeten vastleggen. Een schema wijzigen in een actieve pijplijn veroorzaakt een probleem met achterwaartse compatibiliteit: bestaande geëxtraheerde records gebruiken het oude schema, terwijl nieuwe records het nieuwe gebruiken. Schema-evolutie gaat over het veilig beheren van deze overgang.

Wijs aan elk schema een versienummer toe en sla dit op bij elk geëxtraheerd record. Verhoog het versienummer wanneer je het schema wijzigt. Zo kun je records op schema-versie opvragen, migraties uitvoeren op oude records en afzonderlijke validatielogica voor elke versie behouden. Een eenvoudig tekenreeksveld schema_version in elk uitvoermodel is voldoende.

Toevoegende wijzigingen zijn veilig: een Optional-veld of een veld met een standaardwaarde toevoegen verbreekt oude extractiecode of oude records niet. Ingrijpende wijzigingen zijn riskant: de naam van een veld wijzigen, het type veranderen van string naar int of een veld verwijderen verbreekt downstreamgebruikers. Geef altijd de voorkeur aan toevoegende wijzigingen. Wanneer een ingrijpende wijziging onvermijdelijk is, maak je een nieuwe hoofdversie van het schema en migreer je gecontroleerd.

Neem de schema-versie op in je tabel met extractieresultaten, zodat je altijd weet welke versie elk record heeft geproduceerd. Een jsonb-kolom met de volledige geëxtraheerde gegevens plus een tekstkolom schema_version is een veelgebruikt patroon. Zo kun je versieafhankelijke zoekopdrachten schrijven en oudere records selectief migreren tijdens perioden met weinig verkeer.

Schrijf voor elke overgang tussen schema-versies een migratiescript dat oude records leest, ze omzet naar de nieuwe indeling en ze met de nieuwe versie terugschrijft. Voer migraties uit in kleine reeksen met transacties, zodat een fout de database niet in een gedeeltelijk gemigreerde toestand achterlaat. Houd het oude schema altijd beschikbaar totdat je hebt gecontroleerd dat de migratie is voltooid.

Voer tijdens een schemamigratie parallelle validatie uit: extraheer een steekproef van binnenkomende documenten gelijktijdig met zowel het oude als het nieuwe schema. Vergelijk de resultaten om te controleren of het nieuwe schema alles vastlegt wat het oude vastlegde, plus de nieuwe velden. Schakel het oude schema pas uit nadat parallelle validatie op een statistisch significante steekproef stabiele gelijkwaardigheid heeft aangetoond.

Gebruik functievlaggen om te bepalen wanneer je pijplijn overschakelt van het oude naar het nieuwe schema. Zo kun je het nieuwe schema geleidelijk naar een percentage van het verkeer uitrollen, foutpercentages bewaken en onmiddellijk terugdraaien als er iets misgaat — zonder code opnieuw te implementeren. Diensten voor functievlaggen zoals LaunchDarkly of een eenvoudige databaseregel werken allebei.

Downstreamgebruikers die geëxtraheerde gegevens lezen, moeten meerdere schema-versies goed kunnen verwerken. Gebruik in je code een onderscheiden unietype dat de juiste parserlogica selecteert op basis van het veld schema_version. Dit is robuuster dan voorwaardelijke if-else-ketens schrijven en eenvoudiger uit te breiden wanneer versie 3 verschijnt.

Voer een nieuw schema vóór implementatie uit op je volledige regressietestset: een samengestelde verzameling representatieve documenten met bekende verwachte uitvoer. Vergelijk de F1-scores voor elk veld tussen het oude en nieuwe schema. Een achteruitgang in de F1-score van een veld betekent dat de nieuwe schemabeschrijving het model in verwarring heeft gebracht — verbeter de veldbeschrijving voordat je de wijziging uitbrengt.

Zodra een schema-versie niet meer wordt gebruikt voor nieuwe extracties, kun je deze uitfaseren. Uitfaseren betekent: geen nieuwe records in die versie meer accepteren, oude records leesbaar houden en een einddatum plannen waarop oude records worden gemigreerd of gearchiveerd. Documenteer de uitfasering in een wijzigingslogboek, zodat alle gebruikers weten dat ze hun parsercode moeten bijwerken.

Elke schemawijziging moet vergezeld gaan van een vermelding in het wijzigingslogboek waarin staat wat er is gewijzigd, waarom, hoe je migreert en wat de verwachte gevolgen zijn. Deel vermeldingen uit het wijzigingslogboek met alle teams die geëxtraheerde gegevens gebruiken voordat je de wijziging implementeert. Veel rampen bij schemamigraties ontstaan niet door technische fouten, maar doordat gebruikers niet waren geïnformeerd over een aanstaande wijziging.

In deze les heb je geleerd dat schema-versiebeheer een versieaanduiding opslaat bij elk geëxtraheerd record, zodat je selectief kunt migreren, dat toevoegende wijzigingen veilig zijn terwijl het hernoemen of opnieuw typen van velden een zorgvuldige migratie vereist, en dat parallelle validatie je laat controleren of het nieuwe schema goed werkt voordat je het oude buiten gebruik stelt. Hierna meten we LLM-latentie met de metrieken TTFT en TPOT.