תאימות גרסת TensorFlow

מסמך זה מיועד למשתמשים הזקוקים לתאימות לאחור בגרסאות שונות של TensorFlow (עבור קוד או נתונים), ולמפתחים שרוצים לשנות את TensorFlow תוך שמירה על תאימות.

גירסאות סמנטיות 2.0

TensorFlow כדלקמן סמנטי גרסאות 2.0 ( semver ) עבור API הציבורי שלה. כל גירסה מסחרית של TensorFlow יש צורה MAJOR.MINOR.PATCH . לדוגמה, גרסה 1.2.3 TensorFlow יש MAJOR גרסה 1, MINOR גרסה 2, ו PATCH גרסה 3. שינויים כל מספר יש את הדברים הבאים כלומר:

• עיקריים: פוטנציאלית אחורה שינויים שאינם תואמים. קוד ונתונים שעבדו עם מהדורה מרכזית קודמת לא בהכרח יעבדו עם המהדורה החדשה. עם זאת, במקרים מסוימים, גרפים ונקודות ביקורת קיימים של TensorFlow עשויים להיות ניתנים להעברה למהדורה החדשה יותר; לראות תאימות של גרפי מחסומים לפרטים על תאימות נתונים.

• קטין: Backwards בתכונות תואמות, שיפורים במהירות, וכו 'קוד ונתונים כי עבדו עם שחרור קטין קודם ואשר תלוי רק על ה- API הציבור הלא-ניסיוני ימשיך לעבוד ללא שינוי. לפרטים על מה מקובל ומה לא API הציבורי, לראות מה מכוסה .

• תיקון: Backwards תיקוני באגים תואמים.

לדוגמה, שחרור 1.0.0 הציג שינויים בקנה אחורה ממהדורת 0.12.1. עם זאת, השחרור 1.1.1 היה תואם לאחור עם שחרורו 1.0.0.

מה מכוסה

רק ממשקי ה-API הציבוריים של TensorFlow תואמים לאחור על פני גרסאות משניות ותיקון. ממשקי ה-API הציבוריים מורכבים מ

• כל תיעד Python פונקציות ומחלקות tensorflow המודול submodules שלה, למעט

  • סימנים פרטי: כל פונקציה, בכיתה, וכו ', ששמו מתחיל עם _
  • ניסיוני tf.contrib סימנים, לראות למטה לפרטים.

  שים לב כי את הקוד examples/ ו tools/ ספריות אינו ניתן להשגה באמצעות tensorflow מודול פייתון, ולכן אינו מכוסה על ידי ערבות תאימות.

  אם סמל זמין דרך tensorflow מודול פייתון או submodules שלה, אך אינו מתועד, אז זה לא חלק משיקול API הציבורי.

• ה- API של תאימות (ב Python, את tf.compat מודול). בגרסאות העיקריות, אנו עשויים לשחרר כלי עזר ונקודות קצה נוספות כדי לסייע למשתמשים במעבר לגרסה עיקרית חדשה. סמלי API אלה הוצאו משימוש ואינם נתמכים (כלומר, לא נוסיף תכונות כלשהן, ולא נתקן באגים מלבד תיקון נקודות תורפה), אך הם נופלים תחת ערבויות התאימות שלנו.

• API C .

• קבצי מאגר הפרוטוקול הבאים:

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

מה אינו מכוסה

חלקים מסוימים של TensorFlow יכולים להשתנות בדרכים לא תואמות לאחור בכל נקודה. אלו כוללים:

• ממשקי API ניסיוניים: כדי להקל על פיתוח, אנו לפטור כמה סימני API המסומנים בבירור כניסוי מערבויות התאימות. בפרט, הדברים הבאים אינם מכוסים על ידי ערבויות תאימות כלשהן:

  • כל סמל של tf.contrib מודול או submodules שלה;
  • כל סמל (מודול, פונקציה, טיעון, רכוש, מעמד, או קבוע) ששמו מכיל experimental או Experimental ; אוֹ
  • כל סמל ששמו המלא כולל מודול או מחלקה שהם עצמם ניסיוניים. זה כולל שדות submessages של כל חיץ פרוטוקול שנקרא experimental .

• שפות אחרות: APIs TensorFlow בשפות שאינן Python ו- C, כגון:

  • C ++ (חשוף באמצעות קבצי הכותרת tensorflow/cc ).
  • Java ,
  • ללכת
  • JavaScript

• פרטים של חיילים מיחידות מרוכבים: פונקציות ציבוריות רבות Python להרחיב לכמה ops פרימיטיבי בגרף, ופרטים אלה יהיו חלק מכל גרפים לשמור בדיסק ככל GraphDef ים. פרטים אלה עשויים להשתנות עבור מהדורות קטנות. בפרט, מבחני רגרסיה הבודקים התאמה מדויקת בין גרפים צפויים לפרוץ על פני מהדורות קטנות, למרות שהתנהגות הגרף צריכה להיות ללא שינוי ונקודות ביקורת קיימות עדיין יפעלו.

• צף פרטים מספריים נקודים: הערכים הנקודים צפו הספציפיים מחושבים על ידי ops עשוי להשתנות בכול עת. על המשתמשים להסתמך רק על דיוק משוער ויציבות מספרית, לא על הסיביות הספציפיות המחושבות. שינויים בנוסחאות מספריות במהדורות מינוריות ותיקונים אמורים להביא לדיוק דומה או משופר, עם האזהרה שבלימוד מכונה דיוק משופר של נוסחאות ספציפיות עשוי לגרום לירידה ברמת הדיוק של המערכת הכוללת.

• מספרים אקראיים: מספרים אקראיים ספציפי שחושב עשויים להשתנות בכל עת. על המשתמשים להסתמך רק על התפלגויות נכונות בערך ועל חוזק סטטיסטי, לא על הסיביות הספציפיות המחושבות. עיין דור מספר אקראי המדריך לקבלת פרטים.

• הגרסה להטות ב מופץ Tensorflow: ריצת שתי הגירסות שונות של TensorFlow באשכול בודד אינה נתמכת. אין ערבויות לגבי תאימות לאחור של פרוטוקול החוט.

• באגס: אנו שומרים לעצמנו את הזכות לבצע אחורה התנהגות לא תואמת (אם כי לא API) משנה אם היישום הנוכחי נשבר בבירור, כי הוא, במידה שהוא נוגד את התיעוד או אם ידוע והתנהגות מוגדרים היטב שנועד אינו מיושם כראוי בשל לבאג. לדוגמה, אם אופטימיזר מתיימר ליישם אלגוריתם אופטימיזציה ידוע אך אינו תואם לאלגוריתם זה בגלל באג, אז נתקן את האופטימיזציה. התיקון שלנו עשוי לשבור קוד בהסתמך על התנהגות שגויה להתכנסות. נציין שינויים כאלה בהערות השחרור.

• API בשימוש: אנו שומרים לעצמנו את הזכות לבצע שינויים לאחור עולים בקנה אחד כדי APIs עבורו אין אנו מוצאים שימושים מתועדים (על ידי ביצוע ביקורת של שימוש TensorFlow באמצעות חיפוש GitHub). לפני ביצוע כל שינוי כאמור, נודיע על כוונתנו לבצע את השינוי על רשימת התפוצה להכריז @ , מתן הוראות כיצד להתייחס לכל שבר (אם רלוונטי), ולחכות שבועיים כדי לתת לקהילה שלנו הזדמנות לשתף את המשוב שלהם .

• שגיאת התנהגות: אנו עשויים להחליף שגיאות עם התנהגות בלתי שגיאה. לדוגמה, אנו עשויים לשנות פונקציה כדי לחשב תוצאה במקום להעלות שגיאה, גם אם השגיאה הזו מתועדת. אנו שומרים לעצמנו את הזכות לשנות את הטקסט של הודעות השגיאה. בנוסף, סוג השגיאה עשוי להשתנות אלא אם סוג החריג עבור מצב שגיאה ספציפי מצוין בתיעוד.

תאימות של SavedModels, גרפים ונקודות ביקורת

SavedModel הוא פורמט ההסדרה המועדף לשימוש בתוכניות TensorFlow. SavedModels מכיל שני חלקים: אחד או יותר גרפים מקודדים כמו GraphDefs ומחסום. הגרפים מתארים את זרימת הנתונים של פעולות שיש להפעיל, ונקודות ביקורת מכילות את ערכי הטנזור השמורים של משתנים בגרף.

משתמשי TensorFlow רבים יוצרים SavedModels, ומטעינים ומפעילים אותם עם מהדורה מאוחרת יותר של TensorFlow. בשנת עמידת semver , SavedModels שנכתב עם גרסה אחת של TensorFlow ניתן לטעון ומוערך עם גרסה מתקדמת יותר של TensorFlow עם אותו שחרר.

אנחנו עושים ערבויות נוספות עבור SavedModels נתמך. אנו קוראים SavedModel אשר נוצר באמצעות הלא מומלצת רק, לא-ניסיוני, APIs-תאימות אי 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. לדוגמה (אנחנו משתמשים מספרי גרסאות היפותטיות כאן):

  • 1.2 TensorFlow עשוי לתמוך GraphDef גרסאות 4 עד 7.
  • TensorFlow 1.3 יכול להוסיף GraphDef גרסאות גרסה 8 ותמיכה 4 עד 8.
  • לפחות שישה חודשים מאוחר יותר, TensorFlow 2.0.0 עשויה להפסיק את התמיכה בגרסאות 4 עד 7, ולהשאיר את גרסה 8 בלבד.

  שים לב שבגלל שגרסאות עיקריות של TensorFlow מתפרסמות בדרך כלל בהפרש של יותר מ-6 חודשים, הערבויות עבור SavedModels הנתמכות המפורטות למעלה חזקות בהרבה מהאחריות ל-6 חודשים עבור GraphDefs.

לבסוף, כאשר תמיכת GraphDef גרסה היא ירד, ננסה לספק כלים להמרת גרפים באופן אוטומטי נתמך חדש GraphDef גרסה.

תאימות גרפים ונקודות ביקורת בעת הרחבת TensorFlow

סעיף זה רלוונטי רק בעת ביצוע שינויים בקנה אל GraphDef בפורמט, כגון בעת הוספת ops, הסרת ops, או לשנות את הפונקציונליות של חיילים מיחידות קיימות. הסעיף הקודם אמור להספיק לרוב המשתמשים.

תאימות לאחור וחלקית קדימה

לתוכנית ניהול הגרסאות שלנו יש שלוש דרישות:

• תאימות לאחור טוען גרפים תמיכה ומחסומים שנוצרו בגרסאות ישנות יותר של TensorFlow.
• תאימות קדימה לתרחישי תמיכה שבו המפיק של גרף או למחסום שדרוג לגרסה חדשה של TensorFlow לפני הצרכן.
• אפשר את TensorFlow מתפתח בדרכים לא תואמות. לדוגמה, הסרת פעולות, הוספת תכונות והסרת תכונות.

הערה שבעוד 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 ).

לכל פיסת מידע versioned 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 , שכן מדובר במודלים שאינם משתמשים op זה לא צריך לשבור.

הסר או הגבל את הפונקציונליות של מבצע

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. אם לצרכנים קיימים יש את הגרסה הגרועה, דחוף אותם החוצה בהקדם האפשרי.