این سند برای کاربرانی است که نیاز به سازگاری با نسخههای مختلف 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، مانند:
- C ++ (از طریق فایل های هدر در معرض
tensorflow/cc
). - جاوا ،
- برو
- جاوا اسکریپت
- 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 است.
- TensorFlow 1.2 ممکن است حمایت
در نهایت، زمانی که حمایت برای یک 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
.
یک ویژگی جدید با پیش فرض به یک عملیات موجود اضافه کنید
پیروی از راهنمایی های زیر فقط در صورتی که مجموعه عملیات تغییر نکرده باشد، سازگاری رو به جلو را به شما می دهد:
- اگر سازگاری رو به جلو مورد نظر است، مجموعه ای
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
- این ویژگیهای با ارزش پیشفرض را در زمان تولید/صادرات مدلها حذف میکند. این باعث می شود که صادر
tf.MetaGraphDef
حاوی جدید عملیات، ویژگی نیست که مقدار پیش فرض استفاده شده است. - داشتن این کنترل میتواند به مصرفکنندگان قدیمی (به عنوان مثال، سرویسدهی باینریهایی که از باینریهای آموزشی عقب هستند) اجازه دهد تا بارگذاری مدلها را ادامه دهند و از وقفه در ارائه مدل جلوگیری کنند.
نسخه های در حال تکامل GraphDef
این بخش نحوه استفاده از این مکانیزم نسخه به انواع مختلف تغییرات به GraphDef
فرمت.
یک عملیات اضافه کنید
اضافه کردن عملیات جدید به مصرف کنندگان و تولید کنندگان در همان زمان، و انجام هر گونه تغییر نمی GraphDef
نسخه. این نوع تغییر به طور خودکار با عقب سازگار است و بر برنامه سازگاری رو به جلو تأثیر نمی گذارد زیرا اسکریپت های تولید کننده موجود به طور ناگهانی از عملکرد جدید استفاده نمی کنند.
یک op اضافه کنید و برای استفاده از آن، wrapper های پایتون موجود را تغییر دهید
- پیاده سازی توابع مصرف کننده جدید و افزایش
GraphDef
نسخه. - در صورتی که بتوانید wrapper ها را فقط در مواردی که قبلاً کار نمی کردند از عملکرد جدید استفاده کنند، اکنون می توان wrapper ها را به روز کرد.
- برای استفاده از قابلیت جدید، wrapper های پایتون را تغییر دهید. آیا افزایش نمی
min_consumer
، از مدل هایی که این عملیات استفاده نمی باید پاره کند.
عملکرد یک عملیات را حذف یا محدود کنید
- تمام اسکریپت های تولید کننده (نه خود TensorFlow) را اصلاح کنید تا از عملیات یا عملکرد ممنوعه استفاده نکنید.
- افزایش
GraphDef
نسخه و پیاده سازی توابع مصرف کننده جدید که ممنوعیت عملیات حذف و یا قابلیت برای GraphDefs در نسخه جدید و بالاتر. در صورت امکان، را TensorFlow تولید توقفGraphDefs
با قابلیت های ممنوع شده است. برای این کار، اضافه کردنREGISTER_OP(...).Deprecated(deprecated_at_version, message)
. - منتظر یک نسخه اصلی برای اهداف سازگاری با عقب باشید.
- افزایش
min_producer
به نسخه GraphDef از (2) و حذف قابلیت به طور کامل.
عملکرد یک عملیات را تغییر دهید
- اضافه کردن یک عملیات مشابه جدید به نام
SomethingV2
یا مشابه و از طریق رفتن فرایند اضافه کردن آن و تعویض فوم پیچ دور موجود پایتون آن استفاده کنید. برای اطمینان از استفاده سازگاری رو به جلو چک پیشنهاد در compat.py در هنگام تغییر لفافه پایتون. - عملیات قدیمی را حذف کنید (فقط می تواند با تغییر نسخه اصلی به دلیل سازگاری با عقب انجام شود).
- افزایش
min_consumer
برای رد کردن مصرف کنندگان با عملیات های قدیمی، اضافه کردن تماس عملیات قدیمی به عنوان یک نام مستعار برایSomethingV2
، و رفتن را از طریق فرایند به سوئیچ لفافه موجود پایتون آن استفاده کنید. - برو از طریق این روند به حذف
SomethingV2
.
یک نسخه مصرف کننده ناامن را ممنوع کنید
- دست انداز
GraphDef
نسخه و اضافه کردن نسخه های بد را بهbad_consumers
برای همه GraphDefs جدید است. در صورت امکان، اضافه کردن بهbad_consumers
فقط برای GraphDefs که شامل یک عملیات خاص یا مشابه. - اگر مصرفکنندگان فعلی نسخه بدی دارند، در اسرع وقت آنها را کنار بگذارید.