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

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

نسخه سازی معنایی 2.0

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

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

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

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

به عنوان مثال، انتشار 1.0.0 تغییرات عقب ناسازگار از انتشار 0.12.1 معرفی شده است. با این حال، انتشار 1.1.1 عقب با انتشار 1.0.0 سازگار بود.

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

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

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

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

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

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

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

  • C API .

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

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

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

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

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

  • زبانهای دیگر: رابط های برنامه کاربردی TensorFlow در زبان های غیر از پایتون و C، مانند:

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

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

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

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

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

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

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

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

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

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

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

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

سازگاری GraphDef

نمودارهای از طریق مرتب GraphDef بافر پروتکل. به منظور تسهیل در تغییرات عقب ناسازگار به نمودار، هر GraphDef دارای تعداد نسخه جداگانه از نسخه TensorFlow است. به عنوان مثال، GraphDef نسخه 17 توصیه inv عملیات به نفع 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 به 7 نسخه 4.
    • TensorFlow 1.3 می تواند اضافه کنید GraphDef نسخه 8 و پشتیبانی از نسخه تا 8 4.
    • حداقل شش ماه بعد، TensorFlow 2.0.0 می‌تواند پشتیبانی از نسخه‌های 4 تا 7 را قطع کند و تنها نسخه 8 باقی بماند.

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

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

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

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

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

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

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

توجه داشته باشید که در حالی که GraphDef ساز نسخه جداگانه از نسخه TensorFlow است، تغییرات عقب ناسازگار به GraphDef فرمت هنوز هم توسط معنایی نسخه محدود شده است. این قابلیت به معنای تنها می تواند حذف شود و یا بین تغییر 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 نسخه. این نوع تغییر به طور خودکار با عقب سازگار است و بر برنامه سازگاری رو به جلو تأثیر نمی گذارد زیرا اسکریپت های تولید کننده موجود به طور ناگهانی از عملکرد جدید استفاده نمی کنند.

یک 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 برای رد کردن مصرف کنندگان با عملیات های قدیمی، اضافه کردن تماس عملیات قدیمی به عنوان یک نام مستعار برای SomethingV2 ، و رفتن را از طریق فرایند به سوئیچ لفافه موجود پایتون آن استفاده کنید.
  4. برو از طریق این روند به حذف SomethingV2 .

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

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