OmniDocフィールド名は変わっていませんが、その意味は変わっています;下流では静かにエラーが起こります:抽出結果にバージョン番号を追加することです
先週の `amount` は「セント」を表していましたが、今週は「元」に変更されましたが、フィールド名は変更されていません。型チェックはまだ合格していますが、ビジネス結果は 2 桁悪くなる可能性があります。抽出インターフェイスの最も危険なアップグレードは、多くの場合、エラーを明示的に報告せず、静かに意味を変更することです。
この記事は、ドキュメント抽出インターフェイスを管理する開発者および下流データ チームを対象に書かれています。抽出結果がアップグレードされた後、フィールド名は変更されない場合がありますが、その意味は異なります。たとえば、amount が「fen」から「yuan」に変更された場合でも、型チェックは合格しますが、ビジネス数値は 2 桁異なる可能性があります。
以下では、この種の問題を処理するために、バージョン番号、クリア移行機能、および移行レコードを使用する方法について説明します。これを読むと、どのアップグレードにバージョンの切り替えが必要か、また移行中にどの情報を保持する必要があるかを判断できます。
この記事の例では合成サンプルが使用されており、コードは隔離された環境で例によってチェックされています。これは、すべての実際のファイルや製品の効果を保証するものではありません。重要な書類を処理する前に、原本を保管し、本文の境界と許容事項に従って確認してください。
フィールド名は変更されていませんが、その意味は変更されています。どうやって対処すればいいのでしょうか？一文の結論
各出力に schema_version のラベルを付け、明示的な移行関数を使用して、単に新しいバージョンにラベルを付けるのではなく、異なるバージョンのデータを変換します。
| あなたの状況 | 推奨される実践方法 | 理由 |
|---|---|---|
| フィールドを追加するだけです | 新しいフィールドを追加してバージョンを記録する | フィールドの追加は単位の変更と同じではありません |
| フィールド単位またはセマンティクスの変更 | バージョンごとにバリデーターと移行機能を選択します | 同じ名前のフィールドの意味は静かに変わります |
| 古いレコードには単位が定義されていません | 失敗を明確にし、古いデータを保管し、証拠を追加します | 移行機能は推測であってはなりません |
| ダウンストリームが古いインターフェースを消費しました | バージョン切り替えをスケジュールする | ダウンストリームでは数値的な意味の変更を自動的に検出することは期待できません |
| 抽出結果で翻訳を確認する | 生成されたフィールドのプロトコル バージョン情報を保持する | 「なぜ今回は前回と違うのか」を確認するのに便利です |
バージョン番号はセマンティクスと一致する必要があります
フィールドの追加は単位の変更とは異なります。各出力に schema_version を指定し、バージョンごとにバリデーターと移行関数を選択できます。
バージョン番号だけではシステムは保護されません。すべてのバージョンが同じ未分化の解析ロジックに従っている場合、それは単なる装飾的なフィールドになります。
バージョン管理された解析の鍵
- バージョンごとに解析ルールを選択: バージョンが異なると、独自のバリデーターが使用されます。
- 移行は明示的なデータ変換です。古いデータに直接新しいバージョンのラベルを付けることではありません。
- セマンティックな変更は追跡可能である必要があります: 単位や精度などのルールをレビューできる必要があります。
次の例は、整数のポイントを 10 進数の文字列に変換する方法を示しています。
監査可能な移行機能
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")この例では、入力通貨がパーセント単位の関係を使用し、出力には小数点以下 2 桁があると想定しています。すべての通貨単位をカバーする汎用コンバーターではありません。
type(cents) is int は、True をペニーとして受け入れないように、Python の整数サブクラスとしてブール値を意図的に除外します。
📊 コアの比較: バージョン番号のみとバージョン付き移行
| 練習する | 効果 | 制限事項 |
|---|---|---|
schema_version フィールドのみを追加します | 出力にはバージョンラベルが付属しています | すべてのバージョンが同じ解析ロジックに従っている場合、バージョン番号は単なる装飾的なものになります |
| バージョンごとにバリデータと移行機能を選択する | 同じ名前のフィールドでも、異なるバージョンで明確な説明があります | 各バージョンの変換ルールを明確に明記する必要があります |
移民記録に残すべきものは何でしょうか?
追跡や逸脱処理を促進するために、移行時に以下の情報を記録することが推奨されます。
| 情報 | 目的 | 逃すリスク |
|---|---|---|
| 入力および出力のバージョン | 正しい解釈ルールを選択してください | 同じ名前のフィールドは意味が混同されます |
| プログラムバージョンの移行 | 変換結果を再現してください | 更新後の結果は説明がつかない |
| 元の記録された身元情報 | 原点をたどる | 新旧データは照合できません |
| 失敗の理由 | ハンドリングのための手動迂回 | 未限定データはデフォルト値に置き換えられます |
歴史的な誤りと無限に両立するな
古いレコードの単位自体が不確かであれば、伝達関数を推測すべきではありません。 より適切な方法は、明確な失敗を返却し、古いデータを保持し、補足証拠を求めることです。
すでに古いインターフェースを消費している下流インターフェースについては、数値の意味が変わったことを自動検出することを期待するのではなく、バージョン切り替えも手配すべきです。
翻訳後検証にはバージョン認識も必要です
抽出したフィールドを使ってOmniDoc(製品エントリー)の翻訳をチェックする際は、どのプロトコルがフィールドを生成したかを指定します。 ソースファイルの変更、抽出ルール、ターゲット言語などはマッチング方法に影響を与えます。
バージョン情報を保持することで、「なぜ今回は前回と違うのか」という問題がトラブルシューティングの対象となり、単にモデルの不安定さに帰するのではなくなりましょう。
🎯 どの方法があなたに合いますか?
もしフィールドを加えれば
直接フィールドを追加し、出力にschema_versionを記録します。
単位やフィールドの意味を変えたい場合
新しいバージョンに対して独立した検証器や移行関数を書き、古い解析ロジックは再利用しないでください。
もしあなたの過去のデータユニットが不明瞭なら
移行を明確に失敗にし、元のデータを保持し、証拠を補完してから処理してください。
❓ よくある質問(FAQ)
1. DPSにバージョン番号を追加するだけで十分でしょうか?
まだ足りなかった。 バージョン番号は単なるラベルに過ぎません。すべてのバージョンが同じ解析ロジックを使用している場合、ビジネス上の影響を保護できません。
2. なぜ伝達関数はブール値を除外するのでしょうか?
Pythonでは、ブール値は整数のサブクラスであり、type(cents) is intはTrueがペニーのように受け入れられないようにすることができます。
3. 古いレコードユニットが不確かな場合、どうすればよいでしょうか?
伝達関数は推測してはいけません。 明らかな失敗は返却し、古いデータは保持し、追加の証拠を要求してください。
4. 移住記録に保存すべき情報は何ですか?
最低限、入力・出力バージョン、移行プログラムのバージョン、元のレコード識別子、失敗理由を含めてください。
📝 概要
フィールド名が変わらないからといって、意味が変わらないわけではありません。 出力にバージョン番号を追加し、明示的な移行関数や移行レコードで意味変更を処理することで、静かな下流エラーのリスクを大幅に減らせます。
