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

با مجموعه‌ها، منظم بمانید ذخیره و دسته‌بندی محتوا براساس اولویت‌های شما.

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

نسخه معنایی 2.0

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

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

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

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

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

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

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

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

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

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

    اگر نمادی از طریق ماژول tensorflow پایتون یا زیر ماژول‌های آن در دسترس باشد، اما مستند نباشد، بخشی از API عمومی در نظر گرفته نمی‌شود .

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

  • C API .

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

آنچه تحت پوشش نیست

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

  • APIهای آزمایشی : برای تسهیل توسعه، برخی از نمادهای API که به وضوح به عنوان آزمایشی علامت‌گذاری شده‌اند را از ضمانت‌های سازگاری مستثنی می‌کنیم. به ویژه، موارد زیر تحت هیچ گونه ضمانت سازگاری نیستند:

    • هر نماد در ماژول tf.contrib یا زیر ماژول های آن.
    • هر نماد (ماژول، تابع، آرگومان، ویژگی، کلاس یا ثابت) که نام آن شامل experimental یا Experimental باشد. یا
    • هر نمادی که نام کاملاً واجد شرایط آن شامل یک ماژول یا کلاس است که خود آزمایشی است. این شامل فیلدها و پیام‌های فرعی هر بافر پروتکلی است که experimental نامیده می‌شود.
  • زبان های دیگر : API های TensorFlow در زبان هایی غیر از پایتون و C، مانند:

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

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

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

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

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

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

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

سازگاری SavedModels، نمودارها و نقاط بازرسی

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

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

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

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

سازگاری GraphDef

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

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

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

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

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

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

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

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

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

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

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

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

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

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

توجه داشته باشید که در حالی که مکانیسم نسخه GraphDef از نسخه TensorFlow جدا است، تغییرات ناسازگار با عقب در قالب GraphDef هنوز توسط Semantic Versioning محدود شده است. این بدان معناست که عملکرد فقط بین نسخه های اصلی MAJOR (مانند 1.7 تا 2.0 ) قابل حذف یا تغییر است. علاوه بر این، سازگاری رو به جلو در نسخه‌های Patch اعمال می‌شود ( 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 صادر شده، هنگام استفاده از مقدار پیش‌فرض، دارای ویژگی op-ویژگی جدید نباشد.
  3. داشتن این کنترل می‌تواند به مصرف‌کنندگان قدیمی (به عنوان مثال، سرویس‌دهی باینری‌هایی که از باینری‌های آموزشی عقب هستند) اجازه دهد تا بارگذاری مدل‌ها را ادامه دهند و از وقفه در ارائه مدل جلوگیری کنند.

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

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

یک عملیات اضافه کنید

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

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

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

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

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

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

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

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

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