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áciaOdporúčané postupydôvod
Stačí pridať poliaPridajte nové pole a zaznamenajte verziuPridávanie polí nie je to isté ako zmena jednotiek
Jednotky poľa alebo sémantika sa meniaVyberte validátory a funkcie migrácie podľa verzieVýznam polí s rovnakým názvom sa potichu zmení
Staré záznamy majú nedefinované jednotkyObjasnite zlyhanie, ponechajte staré údaje a pridajte dôkazyMigračné funkcie by nemali byť dohady
Prijímač spotreboval staré rozhranieNaplánujte zmenu verzieNemožno očakávať, že downstream automaticky zistí numerické sémantické zmeny
Skontrolujte preklad s výsledkami extrakcieZachovať informácie o verzii protokolu pre generované poliaJe 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

praxEffectobmedzenia
Pridajte iba pole schema_versionVýstup je označený verziouAk 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 verziePolia s rovnakým názvom majú jasné vysvetlenia v rôznych verziáchPre 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áciepoužitieriziko zmiznutia
Verzie vstupu a výstupuVyberte si správne pravidlo výkladuVýznam polí s rovnakým názvom je mätúci
Verzia migračného programuReprodukujte výsledky konverzieNevysvetliteľné výsledky po aktualizácii
Identita pôvodného záznamuZískať zdrojNové a staré údaje sa nemôžu zhodovať
Dôvod zlyhaniaManuálne spracovanie odklonuNekvalifikované ú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

Aktualizované 2026-11-16