Evoluzione degli schemi e compatibilità con le versioni precedenti

Gli schemi di estrazione non sono statici. I requisiti aziendali cambiano, compaiono nuovi tipi di documenti e si scoprono campi che sarebbe stato opportuno acquisire fin dall'inizio. La modifica di uno schema in una pipeline attiva crea un problema di compatibilità con le versioni precedenti: i record estratti esistenti usano il vecchio schema, mentre i nuovi record usano quello nuovo. La gestione sicura di questa transizione è ciò che si intende per evoluzione dello schema.

Assegni un numero di versione a ogni schema e lo memorizzi insieme a ogni record estratto. Quando modifica lo schema, incrementi la versione. In questo modo può interrogare i record in base alla versione dello schema, eseguire migrazioni sui record precedenti e mantenere una logica di convalida separata per ogni versione. È sufficiente un semplice campo stringa schema_version in ogni modello di output.

Le modifiche additive sono sicure: aggiungere un campo Optional o un campo con un valore predefinito non interrompe il vecchio codice di estrazione né i vecchi record. Le modifiche incompatibili sono rischiose: rinominare un campo, cambiarne il tipo da string a int o rimuoverlo interromperà i consumer downstream. Preferisca sempre le modifiche additive. Quando una modifica incompatibile è inevitabile, crei una nuova versione principale dello schema ed esegua la migrazione in modo controllato.

Includa la versione dello schema nella tabella dei risultati dell'estrazione, così saprà sempre quale versione ha prodotto ogni record. Una colonna jsonb che memorizza tutti i dati estratti, insieme a una colonna di testo schema_version, è un modello comune. Questo consente di scrivere query consapevoli della versione e di migrare selettivamente i record più vecchi durante le finestre di basso traffico.

Scriva uno script di migrazione per ogni transizione tra versioni dello schema: lo script deve leggere i record precedenti, trasformarli nel nuovo formato e riscriverli con la nuova versione. Esegua le migrazioni in piccoli batch con transazioni, così un errore non lascerà il database in uno stato parzialmente migrato. Mantenga sempre disponibile il vecchio schema finché non avrà verificato il completamento della migrazione.

Durante una migrazione dello schema, esegua una convalida parallela: esegua l'estrazione contemporaneamente con il vecchio e il nuovo schema su un campione di documenti in arrivo. Confronti i risultati per verificare che il nuovo schema acquisisca tutto ciò che acquisiva il vecchio, oltre ai nuovi campi. Dismetta il vecchio schema solo dopo che la convalida parallela avrà mostrato una parità stabile su un campione statisticamente significativo.

Usi i feature flag per controllare quando la pipeline passa dal vecchio schema al nuovo. In questo modo può distribuire gradualmente il nuovo schema a una percentuale del traffico, monitorare i tassi di errore e ripristinare immediatamente la versione precedente se qualcosa va storto, senza ridistribuire il codice. Sono adatti sia servizi di feature flag come LaunchDarkly sia una semplice riga nel database.

I consumer downstream che leggono i dati estratti devono gestire correttamente più versioni dello schema. Usi una union discriminata nel codice del consumer, che selezioni la logica di analisi corretta in base al campo schema_version. Questa soluzione è più robusta della scrittura di catene condizionali if-else e più facile da estendere quando arriverà la versione 3.

Prima di distribuire un nuovo schema, lo esegua sull'intero set di test di regressione: una raccolta curata di documenti rappresentativi con output attesi noti. Confronti i punteggi F1 di ogni campo tra il vecchio e il nuovo schema. Una regressione dell'F1 per qualsiasi campo indica che la descrizione del nuovo schema ha confuso il modello: corregga la descrizione del campo prima del rilascio.

Quando una versione dello schema non viene più usata per le nuove estrazioni, può deprecarla. La dismissione significa: smettere di accettare nuovi record in quella versione, mantenere leggibili i record esistenti e pianificare una data di fine utilizzo entro la quale i vecchi record verranno migrati o archiviati. Documenti la dismissione in un changelog, così tutti i consumer sapranno di dover aggiornare il proprio codice di analisi.

Ogni modifica dello schema deve essere accompagnata da una voce nel changelog che descriva cosa è cambiato, perché, le istruzioni per la migrazione e l'impatto previsto. Condivida le voci del changelog con tutti i team che utilizzano i dati estratti prima di distribuire la modifica. Molti disastri nelle migrazioni degli schemi non sono causati da problemi tecnici, ma da consumer che non erano stati informati dell'imminente modifica.

In questa lezione ha imparato che il versioning degli schemi memorizza un identificatore di versione insieme a ogni record estratto, consentendo migrazioni selettive, che le modifiche additive sono sicure, mentre rinominare o modificare il tipo dei campi richiede una migrazione accurata, e che la convalida parallela consente di verificare il nuovo schema prima di dismettere quello precedente. Ora misureremo la latenza degli LLM con le metriche TTFT e TPOT.