التوافق مع إصدار TensorFlow

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

الإصدار الدلالي 2.0

TensorFlow يتبع Semantic Versioning 2.0 ( semver ) لواجهة برمجة التطبيقات العامة الخاصة به. كل نسخة إصدار من TensorFlow لها الشكل MAJOR.MINOR.PATCH . على سبيل المثال ، يحتوي الإصدار 1.2.3 من MINOR على الإصدار MAJOR 1 والإصدار الثاني والثاني PATCH الثالثة. التغييرات على كل رقم لها المعنى التالي:

• رئيسي : تغييرات غير متوافقة مع الإصدارات السابقة. لن تعمل التعليمات البرمجية والبيانات التي عملت مع إصدار رئيسي سابق بالضرورة مع الإصدار الجديد. ومع ذلك ، في بعض الحالات ، قد تكون الرسوم البيانية ونقاط الفحص TensorFlow الحالية قابلة للترحيل إلى الإصدار الأحدث ؛ راجع توافق الرسوم البيانية ونقاط التفتيش للحصول على تفاصيل حول توافق البيانات.

• MINOR : الميزات المتوافقة مع الإصدارات السابقة ، وتحسينات السرعة ، وما إلى ذلك. الشفرة والبيانات التي عملت مع إصدار ثانوي سابق والتي تعتمد فقط على واجهة برمجة التطبيقات العامة غير التجريبية ستستمر في العمل دون تغيير. للحصول على تفاصيل حول ما هو وما هو ليس واجهة برمجة التطبيقات العامة ، راجع ما هو مغطى .

• التصحيح : إصلاحات الأخطاء المتوافقة مع الإصدارات السابقة.

على سبيل المثال ، قدم الإصدار 1.0.0 تغييرات غير متوافقة مع الإصدارات السابقة من الإصدار 0.12.1. ومع ذلك ، كان الإصدار 1.1.1 متوافقًا مع الإصدارات السابقة مع الإصدار 1.0.0.

ما هو مغطى

لا تتوافق سوى واجهات برمجة التطبيقات العامة لـ TensorFlow مع الإصدارات السابقة عبر الإصدارات الثانوية والإصدارات التصحيحية. تتكون واجهات برمجة التطبيقات العامة من

• جميع وظائف وفئات Python الموثقة في وحدة tensorflow الفرعية الخاصة بها ، باستثناء

  • الرموز الخاصة: أي وظيفة ، فئة ، إلخ ، يبدأ اسمها بـ _
  • الرموز التجريبية ورموز tf.contrib ، انظر أدناه للحصول على التفاصيل.

  لاحظ أن الكود الموجود في examples/ tools/ الدلائل لا يمكن الوصول إليه من خلال وحدة tensorflow Python وبالتالي لا يغطيها ضمان التوافق.

  إذا كان الرمز متاحًا من خلال وحدة tensorflow Python أو وحداتها الفرعية ، ولكن لم يتم توثيقه ، فلا يعتبر جزءًا من واجهة برمجة التطبيقات العامة.

• واجهة برمجة تطبيقات التوافق (في Python ، الوحدة النمطية tf.compat ). في الإصدارات الرئيسية ، قد نصدر أدوات مساعدة ونقاط نهاية إضافية لمساعدة المستخدمين في الانتقال إلى إصدار رئيسي جديد. رموز واجهة برمجة التطبيقات هذه مهملة وغير مدعومة (على سبيل المثال ، لن نضيف أي ميزات ، ولن نصلح الأخطاء بخلاف إصلاح الثغرات الأمنية) ، لكنها تندرج ضمن ضمانات التوافق الخاصة بنا.

• واجهة برمجة تطبيقات C.

• ملفات المخزن المؤقت للبروتوكول التالية:

  • attr_value
  • config
  • event
  • graph
  • op_def
  • reader_base
  • summary
  • tensor
  • tensor_shape
  • types

ما لم يتم تغطيته

يمكن أن تتغير بعض أجزاء TensorFlow بطرق غير متوافقة مع الإصدارات السابقة في أي وقت. وتشمل هذه:

• واجهات برمجة التطبيقات التجريبية : لتسهيل التطوير ، نستثني بعض رموز واجهة برمجة التطبيقات التي تم تمييزها بوضوح على أنها تجريبية من ضمانات التوافق. على وجه الخصوص ، لا تغطي أي ضمانات توافق ما يلي:

  • أي رمز في وحدة tf.contrib أو وحداتها الفرعية ؛
  • أي رمز (وحدة نمطية أو دالة أو وسيطة أو خاصية أو فئة أو ثابت) يحتوي اسمه على experimental أو Experimental ؛ أو
  • أي رمز يتضمن اسمه المؤهل بالكامل وحدة أو فئة والتي هي نفسها تجريبية. يتضمن ذلك الحقول والرسائل الفرعية لأي مخزن مؤقت للبروتوكول يسمى experimental .

• لغات أخرى : TensorFlow APIs بلغات أخرى غير Python و C ، مثل:

  • C ++ (مكشوفة من خلال ملفات الرأس في tensorflow/cc ).
  • جافا ،
  • اذهب
  • جافا سكريبت

• تفاصيل العمليات المركبة: تتوسع العديد من الوظائف العامة في Python لتشمل العديد من العمليات الأولية في الرسم البياني ، وستكون هذه التفاصيل جزءًا من أي رسوم بيانية محفوظة على القرص باسم GraphDef s. قد تتغير هذه التفاصيل للإصدارات الطفيفة. على وجه الخصوص ، من المرجح أن تتخطى اختبارات الانحدار التي تتحقق من المطابقة الدقيقة بين الرسوم البيانية إصدارات ثانوية ، على الرغم من أن سلوك الرسم البياني يجب أن لا يتغير وأن نقاط التحقق الحالية ستظل تعمل.

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

• الأرقام العشوائية: قد تتغير الأرقام العشوائية المحددة المحسوبة في أي وقت. يجب أن يعتمد المستخدمون فقط على التوزيعات الصحيحة تقريبًا والقوة الإحصائية ، وليس البتات المحددة المحسوبة. راجع دليل إنشاء الأرقام العشوائية للحصول على التفاصيل.

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

• الأخطاء: نحتفظ بالحق في إجراء تغييرات عكسية للسلوك غير المتوافق (وإن لم يكن واجهة برمجة التطبيقات) في حالة تعطل التطبيق الحالي بشكل واضح ، أي إذا كان يتعارض مع الوثائق أو إذا لم يتم تنفيذ السلوك المقصود المعروف والمحدّد جيدًا بشكل صحيح بسبب لخلل. على سبيل المثال ، إذا ادعى مُحسِّن تنفيذ خوارزمية تحسين معروفة جيدًا ولكنه لا يتطابق مع تلك الخوارزمية بسبب خطأ ، فسنصلح المحسن. قد يؤدي إصلاحنا إلى كسر الشفرة بالاعتماد على السلوك الخاطئ للتقارب. سوف نلاحظ هذه التغييرات في ملاحظات الإصدار.

• واجهة برمجة تطبيقات غير مستخدمة: نحتفظ بالحق في إجراء تغييرات غير متوافقة عكسيًا على واجهات برمجة التطبيقات التي لم نجد لها استخدامات موثقة (عن طريق إجراء تدقيق لاستخدام TensorFlow من خلال بحث GitHub). قبل إجراء أي تغييرات من هذا القبيل ، سنعلن عزمنا على إجراء التغيير على القائمة البريدية للإعلان @ ، وتقديم إرشادات حول كيفية معالجة أي أعطال (إن أمكن) ، والانتظار لمدة أسبوعين لمنح مجتمعنا فرصة لمشاركة ملاحظاتهم. .

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

توافق SavedModels والرسوم البيانية ونقاط التفتيش

SavedModel هو تنسيق التسلسل المفضل للاستخدام في برامج TensorFlow. تحتوي SavedModels على جزأين: رسم بياني واحد أو أكثر مشفر على هيئة GraphDefs تحقق. تصف الرسوم البيانية تدفق البيانات للعمليات التي سيتم تشغيلها ، وتحتوي نقاط التحقق على قيم الموتر المحفوظة للمتغيرات في الرسم البياني.

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

نقدم ضمانات إضافية لـ SavedModels المدعومة . نحن نسمي SavedModel الذي تم إنشاؤه باستخدام واجهات برمجة التطبيقات غير المتوافقة وغير التجريبية وغير المتوافقة فقط في الإصدار الرئيسي من TensorFlow N وهو SavedModel المدعوم في الإصدار N يمكن تحميل أي نموذج SavedModel مدعوم في الإصدار الرئيسي N من TensorFlow وتنفيذه باستخدام الإصدار الرئيسي من TensorFlow N+1 . ومع ذلك ، قد لا تتوفر الوظيفة المطلوبة لإنشاء مثل هذا النموذج أو تعديله بعد الآن ، لذلك لا ينطبق هذا الضمان إلا على SavedModel غير المعدل.

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

التوافق مع GraphDef

يتم إجراء تسلسل للرسوم البيانية عبر المخزن المؤقت لبروتوكول GraphDef . لتسهيل التغييرات العكسية غير المتوافقة على الرسوم البيانية ، يكون لكل GraphDef رقم إصدار منفصل عن إصدار TensorFlow. على سبيل المثال ، ألغى الإصدار 17 من GraphDef inv reciprocal . الدلالات هي:

• يدعم كل إصدار من TensorFlow فاصل زمني من إصدارات GraphDef . سيكون هذا الفاصل الزمني ثابتًا عبر إصدارات التصحيح ، وسيزداد فقط عبر الإصدارات الثانوية. سيحدث إسقاط الدعم لإصدار GraphDef فقط للإصدار الرئيسي من TensorFlow (ويتماشى فقط مع دعم الإصدار المضمون لـ SavedModels).

• يتم تعيين أحدث رقم إصدار من GraphDef التي تم إنشاؤها حديثًا.

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

  لاحظ أن هذا ينطبق فقط على الرسوم البيانية المتسلسلة في GraphDefs (و SavedModels): قد لا يكون الرمز الذي يقرأ نقطة فحص قادرًا على قراءة نقاط التحقق التي تم إنشاؤها بواسطة نفس الرمز الذي يشغل إصدارًا مختلفًا من TensorFlow.

• إذا تمت زيادة الحد الأعلى GraphDef إلى X في إصدار (ثانوي) ، فسيكون هناك ستة أشهر على الأقل قبل زيادة الحد الأدنى إلى X. على سبيل المثال (نستخدم أرقام الإصدارات الافتراضية هنا):

  • قد يدعم GraphDef 1.2 إصدارات GraphDef من 4 إلى 7.
  • يمكن لـ TensorFlow 1.3 إضافة الإصدار 8 من GraphDef ودعم الإصدارات من 4 إلى 8.
  • بعد ستة أشهر على الأقل ، يمكن لـ TensorFlow 2.0.0 إسقاط الدعم للإصدارات من 4 إلى 7 ، مع ترك الإصدار 8 فقط.

  لاحظ أنه نظرًا لأن الإصدارات الرئيسية من TensorFlow يتم نشرها عادةً بعد أكثر من 6 أشهر ، فإن ضمانات SavedModels المدعومة والمفصلة أعلاه أقوى بكثير من ضمان 6 أشهر لـ GraphDefs.

أخيرًا ، عند إسقاط دعم إصدار GraphDef ، سنحاول توفير أدوات للتحويل التلقائي للرسوم البيانية إلى إصدار أحدث مدعوم من GraphDef .

توافق الرسم البياني ونقاط التحقق عند توسيع TensorFlow

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

التوافق مع الإصدارات السابقة والجزئية

يحتوي مخطط الإصدار لدينا على ثلاثة متطلبات:

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

لاحظ أنه على الرغم من أن آلية إصدار GraphDef منفصلة عن إصدار TensorFlow ، فإن التغييرات غير المتوافقة للخلف في تنسيق GraphDef لا تزال مقيدة بواسطة Semantic Versioning. هذا يعني أنه لا يمكن إزالة الوظائف أو تغييرها إلا بين الإصدارات MAJOR من TensorFlow (مثل 1.7 إلى 2.0 ). بالإضافة إلى ذلك ، يتم فرض التوافق إلى الأمام في إصدارات التصحيح ( 1.x.1 إلى 1.x.2 على سبيل المثال).

لتحقيق التوافق مع الإصدارات السابقة والأمامية ومعرفة وقت فرض التغييرات في التنسيقات ، تحتوي الرسوم البيانية ونقاط التحقق على بيانات وصفية تصف وقت إنتاجها. توضح الأقسام أدناه بالتفصيل تنفيذ TensorFlow والإرشادات لتطوير إصدارات GraphDef .

مخططات إصدار البيانات المستقلة

توجد إصدارات مختلفة من البيانات للرسوم البيانية ونقاط التفتيش. يتطور تنسيقي البيانات بمعدلات مختلفة عن بعضهما البعض وأيضًا بمعدلات مختلفة من TensorFlow. تم تعريف كلا نظامي الإصدار في core/public/version.h . عند إضافة إصدار جديد ، تتم إضافة ملاحظة إلى العنوان توضح بالتفصيل ما تم تغييره والتاريخ.

البيانات والمنتجين والمستهلكين

نحن نميز بين الأنواع التالية من معلومات إصدار البيانات:

• المنتجون : الثنائيات التي تنتج البيانات. المنتجون لديهم إصدار ( producer ) وأقل إصدار للمستهلك يتوافقون معه ( min_consumer ).
• المستهلكون : الثنائيات التي تستهلك البيانات. المستهلكون لديهم إصدار ( consumer ) وإصدار منتج أدنى متوافقين مع ( min_producer ).

يحتوي كل جزء من البيانات التي تم إصدارها على حقل VersionDef versions الذي يسجل producer الذي صنع البيانات ، min_consumer الذي يتوافق معه ، وقائمة بالإصدارات bad_consumers غير المسموح بها.

بشكل افتراضي ، عندما يقوم المنتج بعمل بعض البيانات ، ترث البيانات منتج producer وإصدارات min_consumer . يمكن تعيين bad_consumers إذا كان من المعروف أن إصدارات معينة للمستهلك تحتوي على أخطاء ويجب تجنبها. يمكن للمستهلك قبول جزء من البيانات إذا كان كل ما يلي صحيحًا:

• consumer > = min_consumer البيانات
• producer البيانات> = min_producer للمستهلك
• consumer ليس في bad_consumers البيانات

نظرًا لأن كلا من المنتجين والمستهلكين يأتون من نفس قاعدة كود TensorFlow ، فإن core/public/version.h يحتوي على إصدار بيانات رئيسي يتم التعامل معه على أنه producer أو consumer حسب السياق وكلاهما min_consumer و min_producer (يحتاجهما المنتجون والمستهلكون ، على التوالي) . خاصة،

• بالنسبة لإصدارات GraphDef ، لدينا TF_GRAPH_DEF_VERSION و TF_GRAPH_DEF_VERSION_MIN_CONSUMER و TF_GRAPH_DEF_VERSION_MIN_PRODUCER .
• بالنسبة لإصدارات نقاط التفتيش ، لدينا TF_CHECKPOINT_VERSION و TF_CHECKPOINT_VERSION_MIN_CONSUMER و TF_CHECKPOINT_VERSION_MIN_PRODUCER .

أضف سمة جديدة افتراضيًا إلى مرجع موجود

يمنحك اتباع الإرشادات أدناه التوافق مع التوجيه فقط إذا لم تتغير مجموعة العمليات:

1. إذا كان التوافق مع التوجيه مرغوبًا ، strip_default_attrs على True أثناء تصدير النموذج باستخدام إما tf.saved_model.SavedModelBuilder.add_meta_graph_and_variables و tf.saved_model.SavedModelBuilder.add_meta_graph من طراز SavedModelBuilder tf.estimator.Estimator.export_saved_model
2. يؤدي هذا إلى إزالة سمات القيمة الافتراضية في وقت إنتاج / تصدير النماذج. هذا يتأكد من أن tf.MetaGraphDef المُصدَّر لا يحتوي على سمة المرجع الجديدة عند استخدام القيمة الافتراضية.
3. قد يسمح الحصول على عنصر التحكم هذا للمستهلكين القدامى (على سبيل المثال ، خدمة الثنائيات التي تتأخر عن ثنائيات التدريب) بمواصلة تحميل النماذج ومنع الانقطاعات في خدمة النموذج.

تطور إصدارات GraphDef

يوضح هذا القسم كيفية استخدام آلية الإصدار هذه لإجراء أنواع مختلفة من التغييرات على تنسيق GraphDef .

أضف المرجع

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

أضف مرجعًا وقم بتبديل أغلفة Python الحالية لاستخدامها

1. تنفيذ وظائف المستهلك الجديدة وزيادة إصدار GraphDef .
2. إذا كان من الممكن جعل الأغلفة تستخدم الوظيفة الجديدة فقط في الحالات التي لم تنجح من قبل ، فيمكن تحديث الأغلفة الآن.
3. قم بتغيير أغلفة Python لاستخدام الوظيفة الجديدة. لا min_consumer ، لأن النماذج التي لا تستخدم هذا المرجع يجب ألا تنكسر.

إزالة أو تقييد وظيفة المرجع

1. أصلح جميع نصوص المنتج (وليس TensorFlow نفسه) لعدم استخدام المرجع أو الوظيفة المحظورة.
2. قم بزيادة إصدار GraphDef وتنفيذ وظائف المستهلك الجديدة التي تحظر المرجع أو الوظيفة التي تمت إزالتها لـ GraphDefs في الإصدار الجديد وما فوق. إذا أمكن ، اجعل TensorFlow يتوقف عن إنتاج GraphDefs المحظورة. للقيام بذلك ، قم بإضافة REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
3. انتظر إصدارًا رئيسيًا لأغراض التوافق مع الإصدارات السابقة.
4. قم بزيادة min_producer إلى إصدار GraphDef من (2) وإزالة الوظيفة تمامًا.

تغيير وظائف المرجع

1. أضف مرجعًا مشابهًا جديدًا يسمى SomethingV2 أو ما شابه ذلك وانتقل خلال عملية إضافته وتبديل أغلفة Python الحالية لاستخدامه. لضمان التوافق المتقدم ، استخدم عمليات التحقق المقترحة في Compy عند تغيير أغلفة Python.
2. قم بإزالة المرجع القديم (يمكن أن يحدث فقط مع تغيير إصدار رئيسي بسبب التوافق مع الإصدارات السابقة).
3. قم بزيادة min_consumer لاستبعاد المستهلكين مع المرجع القديم ، وأضف المرجع القديم مرة أخرى كاسم مستعار لـ SomethingV2 ، وانتقل خلال العملية لتبديل أغلفة Python الحالية لاستخدامها.
4. انتقل من خلال عملية إزالة SomethingV2 .

حظر إصدار مستهلك واحد غير آمن

1. ارتقِ بإصدار GraphDef وأضف الإصدار السيئ إلى bad_consumers لجميع ملفات GraphDefs الجديدة. إذا أمكن ، أضف إلى bad_consumers فقط لـ GraphDefs التي تحتوي على مرجع معين أو ما شابه ذلك.
2. إذا كان لدى المستهلكين الحاليين النسخة السيئة ، فادفعهم في أسرع وقت ممكن.