Naziv polja nije promijenjen, ali se promijenilo značenje, a nizvodno je tiho napravilo pogrešku: dodajte broj verzije rezultatu ekstrakcije
Prošlotjedni `amount` predstavljao je "cente", ali ovaj tjedan je promijenjen u "yuan", ali naziv polja nije promijenjen. Provjera tipa ipak prolazi, ali poslovni rezultati mogu biti dva reda veličine lošiji. Najopasnija nadogradnja sučelja za ekstrakciju često nije izričito prijaviti grešku, već tiho promijeniti značenje.
Ovaj je članak napisan za programere i podatkovne timove koji održavaju sučelja za ekstrakciju dokumenata. Nakon što se rezultati ekstrakcije nadograde, nazivi polja se možda neće promijeniti, ali će njihova značenja biti drugačija. Na primjer, ako se amount promijeni iz "fen" u "yuan", provjera tipa i dalje prolazi, ali poslovni brojevi mogu se razlikovati za dva reda veličine.
Sljedeće objašnjava kako koristiti brojeve verzija, funkcije brisanja migracije i zapise migracije za rješavanje ove vrste problema. Nakon što ovo pročitate, možete odrediti koje nadogradnje zahtijevaju promjenu verzije i koje informacije treba zadržati tijekom migracije.
Primjeri u ovom članku koriste sintetičke uzorke, a kod je provjeren pomoću primjera u izoliranom okruženju. Ovo ne predstavlja jamstvo svih stvarnih datoteka ili učinaka proizvoda. Prije obrade važnih dokumenata, molimo vas da sačuvate izvornike i pregledate ih prema granicama i stavkama prihvaćanja u tekstu.
Naziv polja nije promijenjen, ali se promijenilo njegovo značenje. Kako se nositi s tim? Zaključak jedne rečenice
Označite svaki izlaz s schema_version i koristite eksplicitne migracijske funkcije za transformaciju različitih verzija podataka umjesto samo označavanja nove verzije.
| vaša situacija | Preporučene prakse | razlog |
|---|---|---|
| Samo dodajte polja | Dodajte novo polje i zabilježite verziju | Dodavanje polja nije isto što i mijenjanje jedinica |
| Promjena jedinica polja ili semantike | Odaberite validatore i funkcije migracije prema verziji | Značenje polja s istim imenom će se tiho promijeniti |
| Stari zapisi imaju nedefinirane jedinice | Razjasnite neuspjeh, zadržite stare podatke i dodajte dokaze | Funkcije migracije ne bi trebale biti nagađanje |
| Nizvodno je iskoristilo staro sučelje | Zakažite promjenu verzije | Ne može se očekivati da nizvodno automatski otkrije numeričke semantičke promjene |
| Provjerite prijevod s rezultatima izdvajanja | Sačuvajte informacije o verziji protokola za generirana polja | Zgodno je provjeriti "zašto se ovaj put razlikuje od prošlog puta" |
Broj verzije treba ići uz semantiku
Dodavanje polja nije isto što i mijenjanje jedinica. Svakom izlazu možete dati schema_version i odabrati validatore i funkcije migracije prema verziji.
Brojevi verzija sami po sebi ne štite sustav. Ako sve verzije slijede istu nediferenciranu logiku raščlanjivanja, to je samo ukrasno polje.
Ključ verzionog parsiranja
- Odaberi pravila raščlanjivanja po verziji: Različite verzije koriste vlastite validatore.
- Migracija je eksplicitna transformacija podataka: ne radi se o označavanju starih podataka izravno novom verzijom.
- Semantičke promjene moraju biti sljedive: pravila kao što su jedinice i preciznost trebaju se moći pregledati.
Sljedeći primjer pokazuje kako pretvoriti cijeli broj bodova u niz decimalnog iznosa.
Migracijska funkcija koja se može revidirati
from decimal import Decimal
def migrate(record):
if record.get("schema_version") != "v1":
raise ValueError("unexpected input version")
cents = record.get("amount_cents")
if type(cents) is not int:
raise ValueError("integer cents required")
return {"schema_version": "v2",
"amount": format(Decimal(cents) / Decimal(100), ".2f"),
"currency": record["currency"]}
old = {"schema_version": "v1", "amount_cents": 12345, "currency": "USD"}
new = migrate(old)
assert new["amount"] == "123.45"
assert old["amount_cents"] == 12345
assert migrate({**old, "amount_cents": -25})["amount"] == "-0.25"
try:
migrate({**old, "amount_cents": True})
except ValueError:
pass
else:
raise AssertionError("bool is not a monetary integer here")
Ovaj primjer pretpostavlja da ulazna valuta koristi odnos postotne jedinice, a izlaz ima dva decimalna mjesta. To nije univerzalni pretvarač koji pokriva sve valutne jedinice.
type(cents) is int namjerno isključuje Booleove vrijednosti kao cjelobrojne podklase u Pythonu kako bi se izbjeglo prihvaćanje True kao penija.
📊 Osnovna usporedba: samo broj verzije i migracija s verzijama
| praksa | Učinak | ograničenja |
|---|---|---|
Dodajte samo polje schema_version | Izlaz je označen verzijom | Ako sve verzije i dalje slijede istu logiku raščlanjivanja, broj verzije samo je ukras |
| Odaberite validatore i funkcije migracije prema verziji | Polja s istim nazivom imaju jasna objašnjenja u različitim verzijama | Morate jasno navesti pravila konverzije za svaku verziju |
Što bi trebalo ostati u evidenciji migracija?
Preporučuje se bilježiti sljedeće informacije tijekom migracije radi olakšavanja praćenja i rukovanja preusmjeravanjem.
| Informacije | Svrha | Rizik propuštanja |
|---|---|---|
| Ulazne i izlazne verzije | Odaberite ispravna pravila interpretacije | Polja s istim imenom imaju zbunjena značenja |
| Migracija verzije programa | Reproducirajte rezultate konverzije | Rezultati nakon ažuriranja su neobjašnjivi |
| Izvorni zabilježeni identitet | Ponovno praćenje izvora | Novi i stari podaci ne mogu se uskladiti |
| Razlozi neuspjeha | Ručno preusmjeravanje radi rukovanja | Nekvalificirani podaci bit će zamijenjeni zadanim vrijednostima |
Nisu beskonačno kompatibilni s povijesnim pogreškama
Ako je jedinica starog zapisa sama po sebi nesigurna, prijenosna funkcija se ne smije nagađati. Prikladniji pristup je vratiti jasan neuspjeh, sačuvati stare podatke i zatražiti dodatne dokaze.
Za downstream sučelja koja su već iskoristila stara sučelja, treba organizirati i prebacivanje verzija, umjesto da se očekuje da će automatski prepoznati promjenu numeričke semantike.
Izvori: Uobičajene ključne riječi JSON sheme
Verifikacija nakon prijevoda također zahtijeva svijest o verziji
Prilikom korištenja izdvojenih polja za provjeru OmniDoc (unos proizvoda) prijevoda, specificirajte koji je protokol generirao polja. Promjene u izvornim datotekama, pravilima za ekstrakciju ili ciljnom jeziku mogu utjecati na metodu podudaranja.
Zadržavanje informacija o verziji čini pitanje "zašto je ovaj put drugačije nego prošli" pitanjem rješavanja problema, umjesto da se jednostavno pripiše nestabilnosti modela.
🎯 Koja ti metoda najviše odgovara?
Ako samo dodaš polje
Izravno dodajte polje i zabilježite schema_version u izlaz.
Ako želiš promijeniti jedinicu ili značenje polja
Pišite neovisne validatore i funkcije migracije za nove verzije i ne koristite staru logiku parsiranja.
Ako vaša povijesna jedinica podataka nije jasna
Napravite da migracija bude jasno neuspješna, zadržite izvorne podatke i procesuirajte tek nakon dopune dokaza.
❓ Često postavljana pitanja (FAQ)
1. Je li dovoljno samo dodati broj verzije DPS-u?
Nedovoljno. Broj verzije je samo oznaka; ako sve verzije i dalje koriste istu logiku parsiranja, ne može zaštititi poslovne implikacije.
2. Zašto prijenosna funkcija isključuje booleanove?
U Pythonu su booleove vrijednosti podklase cijelih brojeva, a type(cents) is int može spriječiti da True bude prihvaćen kao da je novčić.
3. Što trebate učiniti kada je stara ploča neizvjesna?
Prijenosne funkcije ne treba nagađati. Jasni propusti trebaju se vratiti, sačuvati stari podaci i zatražiti dodatni dokazi.
4. Koje informacije treba spremiti u zapise o migraciji?
Najmanje, uključite ulazne i izlazne verzije, verzije programa za migraciju, izvorne identitete zapisa i razloge za neuspjeh.
📝 Sažetak
Nepromijenjena imena polja ne znače da značenje ostaje nepromijenjeno. Dodavanje broja verzije izlazu i rukovanje semantičkim promjenama pomoću eksplicitnih funkcija migracije i zapisa migracije može značajno smanjiti rizik od tihih pogrešaka nizvodno.


