سازگاری نسخه TensorFlow

این سند برای کاربرانی است که به سازگاری معکوس در نسخه های مختلف TensorFlow (چه برای کد یا داده) نیاز دارند و برای توسعه دهندگانی که می خواهند TensorFlow را با حفظ سازگاری اصلاح کنند.

نسخه معنایی 2.0

TensorFlow برای API عمومی خود Semantic Versioning 2.0 ( semver ) را دنبال می کند. هر نسخه منتشر شده از TensorFlow دارای فرم MAJOR.MINOR.PATCH . به عنوان مثال ، TensorFlow نسخه 1.2.3 دارای MAJOR نسخه 1 ، MINOR نسخه 2 و PATCH نسخه 3 است. تغییرات در هر شماره به معنای زیر است:

  • اصلی : تغییرات ناسازگار بالقوه. کد و داده هایی که با نسخه اصلی قبلی کار کرده اند لزوما با نسخه جدید کار نخواهند کرد. با این حال ، در برخی موارد نمودارها و ایست های بازرسی TensorFlow ممکن است به نسخه جدیدتر منتقل شوند. برای جزئیات بیشتر در مورد سازگاری داده ها ، به سازگاری نمودارها و ایست های بازرسی مراجعه کنید.

  • MINOR : ویژگی های سازگار با عقب ، بهبود سرعت و غیره. کد و داده هایی که با نسخه جزئی قبلی کار می کردند و فقط به API عمومی غیر آزمایشی بستگی دارند بدون تغییر کار می کنند. برای جزئیات بیشتر در مورد API عمومی چیست و چیست ، به آنچه تحت پوشش است مراجعه کنید .

  • PATCH : رفع اشکال سازگار به عقب

به عنوان مثال ، نسخه 1.0.0 تغییرات ناسازگار نسبت به نسخه 0.12.1 را ایجاد کرد. با این حال ، نسخه 1.1.1 با نسخه 1.0.0 سازگار بود.

آنچه پوشانده شده است

فقط API های عمومی TensorFlow در نسخه های جزئی و پچ با یکدیگر سازگار هستند. API های عمومی متشکل از

  • همه توابع و کلاسهای پایتون مستند در ماژول tensorflow و زیر مدولهای آن ، به جز

    • نمادهای خصوصی: هر عملکرد ، کلاس و غیره ، که نام آنها با _ شروع می شود
    • نمادهای تجربی و tf.contrib ، برای جزئیات بیشتر به زیر مراجعه کنید.

    توجه داشته باشید که کد موجود در examples/ و tools/ دایرکتوری ها از طریق ماژول tensorflow Python قابل دسترسی tensorflow و بنابراین شامل ضمانت سازگاری نمی شوند.

    اگر نمادی از طریق ماژول tensorflow Python یا tensorflow آن در دسترس باشد ، اما مستند نباشد ، بنابراین بخشی از API عمومی محسوب نمی شود.

  • API سازگاری (در پایتون ، ماژول tf.compat ). در نسخه های اصلی ، ممکن است برنامه های کاربردی و نقاط انتهایی اضافی را برای کمک به کاربران در انتقال به نسخه اصلی جدید منتشر کنیم. این نمادهای API منسوخ شده و پشتیبانی نمی شوند (به عنوان مثال ، ما هیچ ویژگی دیگری اضافه نخواهیم کرد و اشکالی غیر از رفع آسیب پذیری ها برطرف نخواهیم کرد) ، اما مشمول تضمین سازگاری ما هستند.

  • C API .

  • پرونده های بافر پروتکل زیر:

آنچه تحت پوشش قرار نگرفته است

برخی از قسمتهای TensorFlow می توانند در هر نقطه به روشهای ناسازگار عقب تغییر کنند. این شامل:

  • API های آزمایشی : برای تسهیل توسعه ، برخی از نمادهای API را که به عنوان آزمایشی مشخص شده اند ، از ضمانت های سازگاری معاف می کنیم. به طور خاص ، موارد زیر تحت هیچ گونه تضمین سازگاری نیستند:

    • هر نمادی در ماژول tf.contrib یا زیر مدول های آن ؛
    • هر نمادی (ماژول ، تابع ، آرگومان ، ویژگی ، کلاس یا ثابت) که نام آن حاوی experimental یا Experimental . یا

    • هر نمادی که نام آن کاملاً واجد شرایط باشد ، شامل یک ماژول یا کلاس است که خود آزمایشی است. این شامل فیلدها و پیامهای فرعی هر بافر پروتکل به نام experimental .

  • زبانهای دیگر : TensorFlow API ها به زبان های دیگری غیر از Python و C ، مانند:

  • جزئیات عملیات ترکیبی: بسیاری از عملکردهای عمومی در پایتون به چندین عملیات اولیه در نمودار گسترش می یابند و این جزئیات بخشی از نمودارهای ذخیره شده به عنوان GraphDef در دیسک است. این جزئیات ممکن است برای نسخه های جزئی تغییر کند. به طور خاص ، آزمون های رگرسیون که مطابقت دقیق بین نمودارها را بررسی می کنند ، احتمالاً نسخه های جزئی را شکسته اند ، حتی اگر رفتار نمودار بدون تغییر باشد و بازرسی های موجود همچنان کار کنند.

  • جزئیات عددی نقطه شناور: مقادیر خاص نقطه شناور محاسبه شده توسط ops ممکن است در هر زمان تغییر کند. کاربران باید فقط به دقت تقریبی و پایداری عددی اعتماد کنند ، نه به بیت های خاص محاسبه شده. تغییر در فرمول های عددی در نسخه های جزئی و پچ باید منجر به دقت قابل مقایسه یا بهبود شود ، با این تفاوت که در یادگیری ماشین دقت بهتر فرمول های خاص باعث کاهش دقت برای سیستم کلی می شود.

  • اعداد تصادفی: اعداد تصادفی خاص محاسبه شده ممکن است در هر زمان تغییر کنند. کاربران باید فقط به توزیع های تقریباً درست و قدرت آماری اعتماد کنند ، نه بیت های خاص محاسبه شده. برای کسب اطلاعات بیشتر به راهنمای تولید اعداد تصادفی مراجعه کنید.

  • انحراف نسخه در Tensorflow توزیع شده: اجرای دو نسخه مختلف TensorFlow در یک خوشه پشتیبانی نمی شود. هیچ تضمینی در مورد سازگاری معکوس پروتکل سیم وجود ندارد.

  • اشکالات: این حق را برای خود محفوظ می دانیم که اگر اجرای فعلی به وضوح شکسته باشد ، یعنی اگر با اسناد و مدارک مغایرت داشته باشد یا رفتار در نظر گرفته شده کاملاً مشخص و شناخته شده ای به درستی اجرا نشود ، تغییراتی درعمل ناسازگار (هرچند نه API) ایجاد کند به یک اشکال به عنوان مثال ، اگر یک بهینه ساز ادعا می کند که الگوریتم بهینه سازی شناخته شده ای را پیاده سازی می کند اما به دلیل اشکال با آن الگوریتم مطابقت ندارد ، ما بهینه ساز را برطرف خواهیم کرد. رفع اشکال ما ممکن است کد را با تکیه بر رفتار غلط برای همگرایی خراب کند. ما چنین تغییراتی را در یادداشت های انتشار یادداشت خواهیم کرد.

  • API بلااستفاده: ما این حق را برای خود حفظ می کنیم که به صورت معکوس تغییراتی در API ایجاد کنیم که هیچ استفاده مستندی از آن پیدا نمی کنیم (با انجام ممیزی استفاده از TensorFlow از طریق جستجوی GitHub). قبل از انجام هرگونه تغییر ، ما قصد خود را برای ایجاد تغییر در لیست پستی اعلام خواهیم کرد ، دستورالعمل هایی برای نحوه رفع هرگونه شکستگی (در صورت وجود) ارائه می دهیم ، و به مدت دو هفته منتظر می مانیم تا به انجمن خود فرصت دهیم نظرات خود را به اشتراک بگذاریم .

  • رفتار خطا: ممکن است رفتارهای غیرخطا را جایگزین خطاها کنیم. به عنوان مثال ، ما می توانیم به جای ایجاد خطا ، یک عملکرد را برای محاسبه نتیجه تغییر دهیم ، حتی اگر آن خطا مستند باشد. ما همچنین حق تغییر متن پیام های خطا را برای خود محفوظ می دانیم. علاوه بر این ، نوع خطا ممکن است تغییر کند مگر اینکه نوع مستثنی برای یک شرایط خطای خاص در اسناد مشخص شده باشد.

سازگاری مدلهای ذخیره شده ، نمودارها و ایست های بازرسی

SavedModel قالب سریال سازی ترجیحی برای استفاده در برنامه های TensorFlow است. SavedModels حاوی دو قسمت است: یک یا چند نمودار رمزگذاری شده به عنوان GraphDefs و یک Checkpoint. نمودارها جریان داده عملیات مورد اجرا را توصیف می کنند و ایست های بازرسی حاوی مقادیر تنسوری ذخیره شده متغیرها در یک نمودار هستند.

بسیاری از کاربران TensorFlow SavedModels را ایجاد می کنند و آنها را با نسخه بعدی TensorFlow بارگذاری و اجرا می کنند. مطابق با semver ، SavedModels نوشته شده با یک نسخه از TensorFlow را می توان با نسخه بعدی TensorFlow با همان نسخه اصلی بارگیری و ارزیابی کرد.

ما برای SavedModels پشتیبانی شده تضمین های اضافی ارائه می دهیم. ما یک SavedModel که فقط با استفاده از API های غیرقابل استهلاک ، غیرتجربی و غیر سازگاری در نسخه اصلی N TensorFlow ایجاد شده است ، یک SavedModel پشتیبانی شده در نسخه N نامیم . هر SavedModel پشتیبانی در TensorFlow نسخه اصلی N می تواند لود و اجرا با TensorFlow نسخه اصلی N+1 . با این حال ، عملکرد مورد نیاز برای ساخت یا اصلاح چنین مدلی ممکن است دیگر در دسترس نباشد ، بنابراین این ضمانت فقط در مورد SavedModel اصلاح نشده اعمال می شود.

ما تلاش خواهیم کرد تا جایی که امکان دارد سازگاری معکوس را حفظ کنیم ، به طوری که پرونده های سریال شده برای مدت زمان طولانی قابل استفاده هستند.

سازگاری GraphDef

نمودارها از طریق بافر پروتکل GraphDef به صورت سریال GraphDef می شوند. برای تسهیل تغییرات ناسازگار در نمودارها ، هر GraphDef یک شماره نسخه جدا از نسخه GraphDef دارد. به عنوان مثال ، GraphDef نسخه 17 از inv op به سود reciprocal منسوخ شد. معناشناسی عبارتند از:

  • هر نسخه از TensorFlow از فاصله GraphDef نسخه. این فاصله در نسخه های پچ ثابت خواهد بود و فقط در نسخه های جزئی رشد خواهد کرد. حذف پشتیبانی از نسخه GraphDef فقط برای انتشار عمده GraphDef اتفاق می افتد (و فقط با پشتیبانی نسخه تضمین شده برای SavedModels مطابقت دارد).

  • به نمودارهای ایجاد شده جدیدترین شماره نسخه GraphDef اختصاص داده شده است.

  • اگر یک نسخه معین از GraphDef از نسخه GraphDef یک نمودار پشتیبانی کند ، با همان رفتاری که نسخه TensorFlow برای تولید آن استفاده شده بارگیری و ارزیابی می شود (به جز جزئیات عددی شناور و اعداد تصادفی که در بالا ذکر شد) ، صرف نظر از عمده نسخه TensorFlow. به طور خاص ، یک GraphDef که با یک پرونده بازرسی در یک نسخه از TensorFlow سازگار است (مانند موردی که در یک مدل SavedModel وجود دارد) ، تا زمانی که از GraphDef پشتیبانی شود ، با آن نقطه بازرسی سازگار خواهد بود.

    توجه داشته باشید که این تنها به نمودارهای سریال در GraphDefs (و SavedModels) در مورد: کد که بار خوانده شده یک ایستگاه بازرسی ممکن است قادر به خواندن پست های بازرسی تولید شده توسط همان کد در حال اجرا یک نسخه متفاوت از TensorFlow.

  • اگر GraphDef بالای GraphDef در انتشار (جزئی) به X افزایش یابد ، حداقل شش ماه قبل از افزایش حد پایین به X وجود دارد. به عنوان مثال (ما در اینجا از شماره نسخه های فرضی استفاده می کنیم):

    • TensorFlow 1.2 ممکن است از نسخه های GraphDef 4 تا 7 پشتیبانی کند.
    • TensorFlow 1.3 می تواند GraphDef نسخه 8 را اضافه GraphDef و از نسخه های 4 تا 8 پشتیبانی کند.
    • حداقل شش ماه بعد ، TensorFlow 2.0.0 می تواند پشتیبانی از نسخه های 4 تا 7 را رها کند و فقط نسخه 8 را ترک کند.

    توجه داشته باشید که چون نسخه های اصلی TensorFlow معمولاً با فاصله بیش از 6 ماه منتشر می شوند ، ضمانت های مدلهای پشتیبانی شده SavedM که در بالا توضیح داده شد بسیار قویتر از ضمانت 6 ماهه GraphDefs هستند.

سرانجام ، وقتی پشتیبانی از نسخه GraphDef قطع شد ، سعی خواهیم کرد ابزاری برای تبدیل خودکار نمودارها به نسخه GraphDef پشتیبانی جدیدتر ارائه GraphDef .

سازگاری نمودار و ایست بازرسی هنگام گسترش TensorFlow

این بخش فقط هنگام ایجاد تغییرات ناسازگار در قالب GraphDef جمله هنگام افزودن گزینه ها ، حذف عملیات یا تغییر عملکرد گزینه های موجود مرتبط است. بخش قبلی برای اکثر کاربران کافی است.

سازگاری رو به عقب و جزئی

طرح نسخه سازی ما سه نیاز دارد:

  • سازگاری به عقب برای پشتیبانی از بارگذاری نمودارها و ایست های بازرسی ایجاد شده با نسخه های قدیمی تر TensorFlow.
  • سازگاری رو به جلو برای پشتیبانی از سناریوهایی که تولید کننده نمودار یا ایست بازرسی قبل از مصرف کننده به نسخه جدیدتر TensorFlow ارتقا می یابد.
  • TensorFlow در حال تکامل را به روشهای ناسازگار فعال کنید. به عنوان مثال ، حذف ops ، افزودن ویژگی ها و حذف ویژگی ها.

توجه داشته باشید که گرچه GraphDef نسخه GraphDef نسخه GraphDef جدا است ، اما تغییرات ناسازگار در قالب GraphDef همچنان توسط نسخه معنایی محدود می شوند. این قابلیت به معنای تنها می تواند حذف شود و یا بین تغییر MAJOR نسخه های TensorFlow (مانند 1.7 به 2.0 ). علاوه بر این ، سازگاری رو به جلو در نسخه های Patch اعمال می شود (به عنوان مثال 1.x.1 تا 1.x.2 ).

برای دستیابی به سازگاری به عقب و جلو و دانستن اینکه چه زمانی باید تغییرات را در قالب ها اعمال کنید ، نمودارها و ایست های بازرسی دارای فراداده ای هستند که زمان تولید آنها را توصیف می کند. بخشهای زیر جزئیات پیاده سازی GraphDef و رهنمودهای تکامل نسخه های GraphDef .

طرح های نسخه داده های مستقل

نسخه های مختلف داده ای برای نمودارها و ایست های بازرسی وجود دارد. این دو قالب داده با سرعت های مختلف از یکدیگر و همچنین با نرخ های متفاوت از TensorFlow تکامل می یابند. هر دو سیستم نسخه در core/public/version.h تعریف شده اند. هر زمان نسخه جدیدی اضافه می شود ، یادداشتی با عنوان جزئیات تغییر و تاریخ ، به عنوان صفحه اضافه می شود.

داده ها ، تولیدکنندگان و مصرف کنندگان

ما بین انواع زیر اطلاعات نسخه داده را تشخیص می دهیم:

  • تولید کنندگان : باینری هایی که داده تولید می کنند. تولیدکنندگان نسخه ( producer ) و حداقل نسخه مصرف کننده دارند که با آنها سازگار هستند ( min_consumer ).
  • مصرف کنندگان : باینری هایی که داده ها را مصرف می کنند. مصرف کنندگان نسخه ( consumer ) و حداقل نسخه تولید کننده دارند که با آن سازگار هستند ( min_producer ).

هر قطعه از داده های دارای نسخه دارای یک VersionDef versions است که producer که داده را ساخته است ، min_consumer که با آن سازگار است ، و لیستی از نسخه های bad_consumers که مجاز نیستند ، bad_consumers می کند.

به طور پیش فرض ، هنگامی که یک تولید کننده برخی داده ها را ایجاد می کند ، داده ها نسخه های producer و min_consumer تولید کننده را به ارث می 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 .

یک ویژگی جدید به طور پیش فرض به یک op موجود اضافه کنید

پیروی از راهنمایی های زیر فقط در صورتی سازگاری رو به جلوی شما ایجاد می شود که مجموعه گزینه ها تغییر نکرده باشد:

  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 صادر شده حاوی ویژگی جدید op نیست هنگام استفاده از مقدار پیش فرض.
  3. داشتن این کنترل می تواند به مصرف کنندگان قدیمی (به عنوان مثال سرویس های باینری که از آموزش های باینری عقب هستند) اجازه دهد بارگذاری مدل ها را ادامه دهند و از ایجاد وقفه در ارائه مدل جلوگیری کنند.

در حال تکامل نسخه های GraphDef

در این بخش نحوه استفاده از این سازوکار نسخه برای ایجاد انواع مختلف تغییرات در قالب GraphDef است.

اضافه کردن op

گزینه جدید را همزمان به مصرف کنندگان و تولیدکنندگان اضافه کنید و هیچ نسخه GraphDef تغییر GraphDef . این نوع تغییر به طور خودکار سازگار با عقب است و بر برنامه سازگاری رو به جلو تأثیر نمی گذارد ، زیرا اسکریپت های تولید کننده موجود به طور ناگهانی از قابلیت جدید استفاده نمی کنند.

یک op اضافه کنید و برای استفاده از آن بسته بندی های موجود Python را تغییر دهید

  1. عملکرد جدید مصرف کننده را پیاده سازی کرده و نسخه GraphDef را افزایش GraphDef .
  2. اگر می توان فقط در مواردی که قبلاً کار نمی کردند ، از کاغذهای بسته بندی جدید استفاده کرد ، اکنون می توان بسته بندی ها را به روز کرد.
  3. برای استفاده از قابلیت های جدید ، بسته های پایتون را تغییر دهید. min_consumer افزایش min_consumer ، زیرا مدلهایی که از این گزینه استفاده نمی کنند نباید خراب شوند.

عملکرد یک op را حذف یا محدود کنید

  1. برای استفاده نکردن از اپ یا عملکرد ممنوع ، همه اسکریپت های تولید کننده (نه خود TensorFlow) را برطرف کنید.
  2. نسخه GraphDef را افزایش GraphDef و عملکرد جدید مصرف کننده را اعمال کنید که عملکرد یا عملکرد حذف شده برای GraphDefs را در نسخه جدید و بالاتر ممنوع می کند. در صورت امکان ، GraphDefs از تولید GraphDefs با قابلیت ممنوع متوقف کنید. برای انجام این کار ، REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
  3. برای اهداف سازگاری به عقب منتظر یک نسخه اصلی باشید.
  4. min_producer را از (2) به نسخه min_producer افزایش min_producer و عملکرد را کاملاً حذف کنید.

عملکرد یک op را تغییر دهید

  1. یک اپلیکیشن مشابه جدید به نام SomethingV2 یا مشابه اضافه کنید و مراحل اضافه کردن آن و تغییر دادن بسته بندی های موجود پایتون را برای استفاده از آن انجام دهید. برای اطمینان از سازگاری رو به جلو ، هنگام تغییر پوشه های پایتون از چک های پیشنهادی در compat.py استفاده کنید.
  2. op قدیمی را حذف کنید (فقط با تغییر نسخه اصلی به دلیل سازگاری با عقب ، امکان پذیر است).
  3. min_consumer افزایش min_consumer تا مصرف کنندگان با op قدیمی حذف شوند ، op قدیمی را به عنوان مستعار برای SomethingV2 و مراحل استفاده را برای تغییر دادن بسته بندی های موجود Python ادامه دهید.
  4. مراحل را برای حذف SomethingV2 .

یک نسخه مصرف کننده ناامن منع کنید

  1. نسخه GraphDef از دست GraphDef و نسخه بد را برای bad_consumers برای تمام GraphDefs جدید اضافه کنید. در صورت امکان ، فقط برای GraphDefs که دارای یک گزینه خاص یا موارد مشابه هستند به bad_consumers اضافه کنید.
  2. اگر مصرف کنندگان موجود نسخه بدی دارند ، آنها را در اسرع وقت بیرون رانید.