De veldnaam is niet veranderd, maar de betekenis is veranderd, en de downstream heeft stilletjes een fout gemaakt: voeg een versienummer toe aan het extractieresultaat

Dit artikel is geschreven voor ontwikkelaars en downstream-datateams die interfaces voor documentextractie onderhouden. Nadat de extractieresultaten zijn geüpgraded, veranderen de veldnamen mogelijk niet, maar hun betekenis zal anders zijn. Als amount bijvoorbeeld wordt gewijzigd van "fen" in "yuan", slaagt de typecontrole nog steeds, maar kunnen de bedrijfsnummers twee ordes van grootte verschillen.

Hieronder wordt uitgelegd hoe u versienummers, duidelijke migratiefuncties en migratierecords kunt gebruiken om dit soort problemen op te lossen. Nadat u dit heeft gelezen, kunt u bepalen voor welke upgrades er van versie moet worden gewisseld en welke informatie tijdens de migratie moet worden bewaard.

De voorbeelden in dit artikel maken gebruik van synthetische samples en de code is gecontroleerd door de voorbeelden in een geïsoleerde omgeving. Dit vormt geen garantie voor alle echte bestanden of producteffecten. Voordat u belangrijke documenten verwerkt, dient u de originelen te bewaren en deze te controleren op basis van de grenzen en acceptatie-items in de tekst.

De veldnaam is niet veranderd, maar de betekenis ervan is veranderd. Hoe ermee om te gaan? Conclusie in één zin

Label elke uitvoer met schema_version en gebruik expliciete migratiefuncties om verschillende versies van de gegevens te transformeren in plaats van alleen maar een nieuwe versie te labelen.

Het versienummer moet overeenkomen met de semantiek

Het toevoegen van een veld is niet hetzelfde als het wijzigen van eenheden. U kunt elke uitvoer schema_version geven en validators en migratiefuncties per versie selecteren.

Versienummers op zichzelf beschermen het systeem niet. Als alle versies dezelfde ongedifferentieerde parseerlogica volgen, is dit slechts een decoratief veld.

De sleutel tot parseren met versiebeheer

• Selecteer parseerregels per versie: verschillende versies gebruiken hun eigen validators.
• Migratie is een expliciete datatransformatie: het gaat niet om het direct labelen van oude data met een nieuwe versie.
• Semantische veranderingen moeten traceerbaar zijn: regels zoals eenheden en precisie moeten kunnen worden herzien.

In het volgende voorbeeld ziet u hoe u een geheel aantal punten converteert naar een decimale hoeveelheidsreeks.

Een controleerbare migratiefunctie

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")

In dit voorbeeld wordt ervan uitgegaan dat de invoervaluta een procentuele eenheidsrelatie gebruikt en dat de uitvoer twee decimalen heeft. Het is geen universele converter die alle munteenheden bestrijkt.

type(cents) is int sluit opzettelijk Booleaanse waarden uit als subklassen met gehele getallen in Python om te voorkomen dat True als een cent wordt geaccepteerd.

📊 Kernvergelijking: alleen versienummer en migratie op versieniveau

Wat moet er in het migratierecord blijven staan?

Het wordt aanbevolen om tijdens de migratie de volgende informatie vast te leggen om backtracking en offload-verwerking te vergemakkelijken.

Wees niet oneindig compatibel met historische fouten

Als de eenheden van het oude record zelf onzeker zijn, mag de migratiefunctie niet raden. Een geschiktere aanpak is om een expliciete fout te melden, de oude gegevens te behouden en om aanvullend bewijsmateriaal te vragen.

Voor downstreamgebruikers die de oude interface al gebruiken, moet ook versiewisseling worden geregeld, in plaats van te verwachten dat deze automatisch ontdekt dat de waardesemantiek is veranderd.

Bronnen: Algemene trefwoorden voor JSON-schema

Verificatie na vertaling vereist ook versiekennis

Wanneer u geëxtraheerde velden gebruikt om OmniDoc (productportaal)-vertalingen te controleren, moet u aangeven via welk protocol de velden zijn gegenereerd. Wijzigingen in bronbestanden, extractieregels of doeltaal kunnen van invloed zijn op de vergelijkingsmethode.

Het bewaren van versie-informatie kan ervoor zorgen dat "waarom deze keer anders is dan de vorige keer" een probleem kan worden opgelost, in plaats van dit eenvoudigweg toe te schrijven aan modelinstabiliteit.

🎯 Welke methode is geschikt voor jou?

Als u gewoon een nieuw veld toevoegt

Voeg direct een nieuw veld toe en neem schema_version op in de uitvoer.

Als u de eenheid of betekenis van een veld wilt wijzigen

Schrijf onafhankelijke validators en migratiefuncties voor de nieuwe versie en gebruik geen oude parseerlogica.

Als uw historische gegevenseenheid niet duidelijk is

Maak duidelijk dat de migratie is mislukt, bewaar de originele gegevens en voeg bewijsmateriaal toe voordat de migratie wordt verwerkt.

❓ Veelgestelde vragen (FAQ)

1. Is het voldoende om gewoon een versienummer aan de uitvoer toe te voegen?

niet genoeg. Het versienummer is slechts een label en kan de zakelijke betekenis niet beschermen als alle versies nog steeds dezelfde parseerlogica gebruiken.

2. Waarom sluit de migratiefunctie Booleaanse waarden uit?

Booleaanse waarden in Python zijn een subklasse van gehele getallen, en type(cents) is int voorkomt dat True als een cent wordt geaccepteerd.

3. Wat moet je doen als de oude platenspeler niet zeker is?

Migratiefuncties mogen niet worden vermoed. Een expliciete fout moet worden geretourneerd, de oude gegevens moeten worden bewaard en er moet aanvullend bewijs worden gevraagd.

4. Welke informatie moet in de migratierecords worden opgeslagen?

Vermeld minimaal de invoer- en uitvoerversies, de versie van het migratieprogramma, de identiteit van het oorspronkelijke record en de reden van de fout.

📝 Samenvatting

Het feit dat de veldnaam ongewijzigd blijft, betekent niet dat de betekenis ongewijzigd blijft. Het versiebeheer van de uitvoer en het verwerken van semantische wijzigingen met expliciete migratiefuncties en migratierecords kan het risico op stille fouten stroomafwaarts aanzienlijk verminderen.

Probeer het nu: upload het document om de vertaling te starten, waarbij de oorspronkelijke lay-out behouden blijft