Názov poľa sa nezmenil, ale význam sa zmenil a následný používateľ potichu urobil chybu: k výsledku extrakcie pridajte číslo verzie
Minulotýždňové `amount` predstavovalo "centy", ale tento týždeň sa zmenilo na "yuan", ale názov poľa sa nezmenil. Typová kontrola ešte prejde, ale obchodné výsledky môžu byť o dva rády horšie. Najnebezpečnejšou inováciou rozhrania extrakcie často nie je explicitne nahlásiť chybu, ale potichu zmeniť význam.
Tento článok je napísaný pre vývojárov a nadväzujúce dátové tímy, ktoré spravujú rozhrania na extrakciu dokumentov. Po aktualizácii výsledkov extrakcie sa názvy polí nemusia zmeniť, ale ich význam sa bude líšiť. Ak sa napríklad amount zmení z „fen"na „yuan", typová kontrola stále prebehne, ale obchodné čísla sa môžu líšiť o dva rády.
Nasledujúci text vysvetľuje, ako používať čísla verzií, vymazať funkcie migrácie a záznamy migrácie na riešenie tohto typu problému. Po prečítaní tohto dokumentu môžete určiť, ktoré aktualizácie vyžadujú zmenu verzie a aké informácie by sa mali počas migrácie zachovať.
Príklady v tomto článku používajú syntetické vzorky a kód bol skontrolovaný pomocou príkladov v izolovanom prostredí. Toto nepredstavuje záruku všetkých skutočných súborov alebo efektov produktu. Pred spracovaním dôležitých dokumentov si uschovajte originály a skontrolujte ich podľa hraníc a akceptačných položiek v texte.
Názov poľa sa nezmenil, ale zmenil sa jeho význam. Ako sa s tým vysporiadať? Záver jednou vetou
Označte každý výstup pomocouschema_version a použite funkcie explicitnej migrácie na transformáciu rôznych verzií údajov namiesto jednoduchého označenia novej verzie.
| vaša situácia | Odporúčané postupy | dôvod |
|---|---|---|
| Stačí pridať polia | Pridajte nové pole a zaznamenajte verziu | Pridávanie polí nie je to isté ako zmena jednotiek |
| Jednotky poľa alebo sémantika sa menia | Vyberte validátory a funkcie migrácie podľa verzie | Význam polí s rovnakým názvom sa potichu zmení |
| Staré záznamy majú nedefinované jednotky | Objasnite zlyhanie, ponechajte staré údaje a pridajte dôkazy | Migračné funkcie by nemali byť dohady |
| Prijímač spotreboval staré rozhranie | Naplánujte zmenu verzie | Nemožno očakávať, že downstream automaticky zistí numerické sémantické zmeny |
| Skontrolujte preklad s výsledkami extrakcie | Zachovať informácie o verzii protokolu pre generované polia | Je vhodné skontrolovať „prečo je tento čas iný ako naposledy" |
Číslo verzie by malo zodpovedať sémantike
Pridanie poľa nie je to isté ako zmena jednotiek. Každému výstupu môžete daťschema_version a vybrať validátory a funkcie migrácie podľa verzie.
Čísla verzií samotné nechránia systém. Ak všetky verzie sledujú rovnakú nediferencovanú logiku analýzy, je to len dekoratívne pole.
Kľúč k analýze verzií
- Vybrať pravidlá analýzy podľa verzie: Rôzne verzie používajú svoje vlastné validátory.
- Migrácia je explicitná transformácia údajov: nejde o priame označenie starých údajov novou verziou.
- Sémantické zmeny musia byť sledovateľné: pravidlá, ako sú jednotky a presnosť, by sa mali dať preskúmať.
Nasledujúci príklad ukazuje, ako previesť celý počet bodov na reťazec desatinných hodnôt.
Kontrolovateľná funkcia migrácie
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")
Tento príklad predpokladá, že vstupná mena používa vzťah jednotiek percent a výstup má dve desatinné miesta. Nie je to univerzálny prevodník pokrývajúci všetky menové jednotky.
type(cents) is int zámerne vylučuje booleovské hodnoty ako celočíselné podtriedy v Pythone, aby sa vyhlo akceptovaniu True ako centu.
📊 Porovnanie jadra: iba číslo verzie a migrácia verzie
| prax | Effect | obmedzenia |
|---|---|---|
Pridajte iba pole schema_version | Výstup je označený verziou | Ak všetky verzie stále dodržiavajú rovnakú logiku analýzy, číslo verzie je len ozdobou |
| Vyberte validátory a funkcie migrácie podľa verzie | Polia s rovnakým názvom majú jasné vysvetlenia v rôznych verziách | Pre každú verziu je potrebné zapísať pravidlá konverzie |
Čo by malo zostať v zázname migrácie?
Počas migrácie sa odporúča zaznamenať nasledujúce informácie, aby sa uľahčilo spätné sledovanie a vykladanie.
| informácie | použitie | riziko zmiznutia |
|---|---|---|
| Verzie vstupu a výstupu | Vyberte si správne pravidlo výkladu | Význam polí s rovnakým názvom je mätúci |
| Verzia migračného programu | Reprodukujte výsledky konverzie | Nevysvetliteľné výsledky po aktualizácii |
| Identita pôvodného záznamu | Získať zdroj | Nové a staré údaje sa nemôžu zhodovať |
| Dôvod zlyhania | Manuálne spracovanie odklonu | Nekvalifikované údaje sú vyplnené predvolenými hodnotami |
Nebuďte nekonečne kompatibilný s historickými chybami
Ak sú jednotky starého záznamu samé osebe neisté, funkcia migrácie by nemala hádať. Vhodnejším prístupom je vrátiť explicitné zlyhanie, ponechať staré údaje a požiadať o ďalšie dôkazy.
Pre následných používateľov, ktorí už používajú staré rozhranie, by sa malo zabezpečiť aj prepínanie verzií, namiesto toho, aby sa očakávalo, že automaticky zistí, že sa zmenila sémantika hodnôt.
Zdroje: Bežné kľúčové slová schémy JSON
Overenie po preklade tiež vyžaduje povedomie o verzii
Pri používaní extrahovaných polí na kontrolu prekladov OmniDoc (produktový portál) by ste mali uviesť, ktorým protokolom boli polia vygenerované. Zmeny v zdrojových súboroch, pravidlách extrakcie alebo cieľovom jazyku môžu ovplyvniť metódu porovnávania.
Zachovanie informácií o verzii môže spôsobiť, že „prečo je tento čas iný ako minulý"problém, ktorý možno vyriešiť namiesto jednoduchého pripisovania nestabilite modelu.
🎯 Ktorá metóda je pre vás vhodná?
Ak práve pridáte nové pole
Priamo pridajte nové pole a vo výstupe zaznamenajteschema_version.
Ak chcete upraviť jednotku alebo význam poľa
Napíšte nezávislé validátory a funkcie migrácie pre novú verziu a nepoužívajte znova starú logiku analýzy.
Ak vaša jednotka historických údajov nie je jasná
Pred spracovaním objasnite, že migrácia zlyhala, ponechajte pôvodné údaje a pridajte dôkazy.
❓ Často kladené otázky (FAQ)
1. Stačí na výstup pridať číslo verzie?
nestačí. Číslo verzie je len štítok a nemôže chrániť obchodný význam, ak všetky verzie stále používajú rovnakú logiku analýzy.
2. Prečo funkcia migrácie vylučuje boolovské hodnoty?
Booleovské hodnoty v Pythone sú podtriedou celých čísel a type(cents) is int bráni akceptovaniu True ako centu.
3. Čo by ste mali robiť, keď je stará záznamová jednotka neistá?
Migračné funkcie by sa nemali hádať. Výslovné zlyhanie by sa malo vrátiť, staré údaje by sa mali ponechať a mali by sa vyžiadať ďalšie dôkazy.
4. Aké informácie je potrebné uložiť do záznamov migrácie?
Zahrňte minimálne vstupné a výstupné verzie, verziu migračného programu, identitu pôvodného záznamu a dôvod zlyhania.
📝 Zhrnutie
Skutočnosť, že názov poľa zostane nezmenený, neznamená, že význam zostane nezmenený. Verzia výstupu a spracovanie sémantických zmien pomocou explicitných migračných funkcií a záznamov migrácie môže výrazne znížiť riziko tichých chýb v smere toku.
Skúste to teraz: Odovzdajte dokument a spustite preklad, pričom sa zachová pôvodné rozloženie


