لم يتغير اسم الحقل ولكن المعنى تغير، وارتكب المصب خطأً بهدوء: أضف رقم الإصدار إلى نتيجة الاستخراج

هذه المقالة مكتوبة للمطورين وفرق البيانات النهائية التي تحافظ على واجهات استخراج المستندات. بعد ترقية نتائج الاستخراج، قد لا تتغير أسماء الحقول، ولكن معانيها ستكون مختلفة. على سبيل المثال، إذا تم تغيير amount من "fen" إلى "yuan"، فسيستمر التحقق من النوع، ولكن قد تختلف أرقام الأعمال بمقدار أمرين من حيث الحجم.

يوضح ما يلي كيفية استخدام أرقام الإصدارات ومسح وظائف الترحيل وسجلات الترحيل للتعامل مع هذا النوع من المشكلات. بعد قراءة هذا، يمكنك تحديد الترقيات التي تتطلب تبديل الإصدار، وما هي المعلومات التي يجب الاحتفاظ بها أثناء الترحيل.

تستخدم الأمثلة الموجودة في هذه المقالة عينات تركيبية، وقد تم التحقق من التعليمات البرمجية بواسطة الأمثلة الموجودة في بيئة معزولة. وهذا لا يمثل ضمانًا لجميع الملفات الحقيقية أو تأثيرات المنتج. قبل معالجة المستندات المهمة، يرجى الاحتفاظ بالنسخ الأصلية ومراجعتها وفقًا للحدود وبنود القبول في النص.

اسم الحقل لم يتغير ولكن معناه تغير. كيفية التعامل معها؟ استنتاج جملة واحدة

قم بتسمية كل مخرجات باستخدام schema_version واستخدم وظائف الترحيل الصريحة لتحويل إصدارات مختلفة من البيانات بدلاً من مجرد تسمية إصدار جديد.

يجب أن يتوافق رقم الإصدار مع الدلالات

إن إضافة حقل لا يعني تغيير الوحدات. يمكنك إعطاء كل مخرجات schema_version وتحديد أدوات التحقق من الصحة ووظائف الترحيل حسب الإصدار.

أرقام الإصدارات في حد ذاتها لا تحمي النظام. إذا اتبعت جميع الإصدارات نفس منطق التحليل غير المتمايز، فهذا مجرد حقل زخرفي.

مفتاح تحليل الإصدارات

• حدد قواعد التحليل حسب الإصدار: تستخدم الإصدارات المختلفة أدوات التحقق الخاصة بها.
• الترحيل عبارة عن تحويل واضح للبيانات: لا يتعلق الأمر بتسمية البيانات القديمة مباشرة بإصدار جديد.
• يجب أن تكون التغييرات الدلالية قابلة للتتبع: يجب أن تكون القواعد مثل الوحدات والدقة قابلة للمراجعة.

يوضح المثال التالي كيفية تحويل عدد صحيح من النقاط إلى سلسلة مبلغ عشري.

وظيفة ترحيل قابلة للتدقيق

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

يفترض هذا المثال أن عملة الإدخال تستخدم علاقة وحدة النسبة المئوية وأن الإخراج يحتوي على منزلتين عشريتين. إنه ليس محولًا عالميًا يغطي جميع وحدات العملة.

يستبعد type(cents) is int القيم المنطقية عمدًا كفئة فرعية صحيحة في Python لتجنب قبول True كبنس واحد.

📊 المقارنة الأساسية: رقم الإصدار فقط وترحيل الإصدار

ما الذي يجب تركه في سجل الهجرة؟

يوصى بتسجيل المعلومات التالية أثناء الترحيل لتسهيل عملية التتبع والتفريغ.

لا تكن متوافقًا بشكل لا نهائي مع الأخطاء التاريخية

إذا كانت وحدات السجل القديم نفسها غير مؤكدة، فلا ينبغي لوظيفة الترحيل التخمين. النهج الأكثر ملاءمة هو إرجاع الفشل الصريح، والاحتفاظ بالبيانات القديمة، وطلب أدلة إضافية.

بالنسبة للمستخدمين النهائيين الذين يستهلكون الواجهة القديمة بالفعل، يجب أيضًا ترتيب تبديل الإصدار، بدلاً من توقع اكتشافهم تلقائيًا أن دلالات القيمة قد تغيرت.

المراجع: الكلمات الرئيسية الشائعة لمخطط JSON

يتطلب التحقق بعد الترجمة أيضًا معرفة الإصدار

عند استخدام الحقول المستخرجة للتحقق من ترجمات OmniDoc (بوابة المنتج)، يجب عليك الإشارة إلى البروتوكول الذي تم إنشاء الحقول من خلاله. قد تؤثر التغييرات في الملفات المصدر أو قواعد الاستخراج أو اللغة الهدف على طريقة المقارنة.

يمكن أن يؤدي الاحتفاظ بمعلومات الإصدار إلى جعل "سبب اختلاف هذه المرة عن المرة السابقة" مشكلة قابلة لاستكشاف الأخطاء وإصلاحها بدلاً من إسنادها ببساطة إلى عدم استقرار النموذج.

🎯 ما هي الطريقة المناسبة لك؟

إذا قمت فقط بإضافة حقل جديد

قم بإضافة حقل جديد مباشرة وقم بتسجيل schema_version في الإخراج.

إذا كنت تريد تعديل وحدة أو معنى الحقل

اكتب أدوات التحقق المستقلة ووظائف الترحيل للإصدار الجديد، ولا تعيد استخدام منطق التحليل القديم.

إذا كانت وحدة البيانات التاريخية الخاصة بك غير واضحة

وضح فشل الترحيل، واحتفظ بالبيانات الأصلية، وأضف الأدلة قبل المعالجة.

❓ الأسئلة الشائعة (الأسئلة الشائعة)

1. هل يكفي مجرد إضافة رقم الإصدار إلى المخرجات؟

لا يكفي. رقم الإصدار هو مجرد تصنيف، ولا يمكنه حماية المعنى التجاري إذا كانت جميع الإصدارات لا تزال تستخدم نفس منطق التحليل.

2. لماذا تستبعد وظيفة الترحيل القيم المنطقية؟

القيم المنطقية في بايثون هي فئة فرعية من الأعداد الصحيحة، ويمنع type(cents) is int قبول True كبنس واحد.

3. ماذا يجب أن تفعل عندما تكون وحدة التسجيل القديمة غير مؤكدة؟

لا ينبغي تخمين وظائف الهجرة. وينبغي إرجاع الفشل الصريح، والاحتفاظ بالبيانات القديمة، وطلب أدلة إضافية.

4. ما هي المعلومات التي يجب حفظها في سجلات الترحيل؟

كحد أدنى، قم بتضمين إصدارات الإدخال والإخراج وإصدار برنامج الترحيل وهوية السجل الأصلي وسبب الفشل.

📝 ملخص

حقيقة أن اسم الحقل لم يتغير لا يعني أن المعنى لم يتغير. يمكن أن يؤدي تعيين إصدار المخرجات ومعالجة التغييرات الدلالية باستخدام وظائف الترحيل الواضحة وسجلات الترحيل إلى تقليل مخاطر الأخطاء الصامتة بشكل كبير.

جربه الآن: قم بتحميل المستند لبدء الترجمة، مع الاحتفاظ بالتخطيط الأصلي