תאימות גרסת TensorFlow

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

גרסא סמנטית 2.0

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

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

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

• PATCH : תיקוני באגים תואמים לאחור.

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

מה מכוסה

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

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

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

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

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

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

• ממשק ה- API .

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

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

מה לא מכוסה

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

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

  • כל סמל במודול tf.contrib או מודולי tf.contrib שלו;

  • כל סמל (מודול, פונקציה, טיעון, נכס, מחלקה או קבוע) ששמו מכיל experimental או Experimental ; אוֹ

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

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

  • C ++ (נחשף דרך קבצי כותרת ב- tensorflow/cc ).
  • ג'אווה ,
  • ללכת
  • JavaScript

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

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

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

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

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

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

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

תאימות של מודלים, גרפים ומחסומים שמורים

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

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

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

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

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

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

תאימות גרפים ומחסומים בעת הרחבת TensorFlow

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

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

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

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

שים לב שבעוד GraphDef גרסת GraphDef נפרד מגרסת TensorFlow, שינויים בלתי תואמים לאחור בפורמט GraphDef עדיין מוגבלים על ידי גירסאות סמנטיות. פירוש הדבר שניתן להסיר או לשנות פונקציונליות רק בין גרסאות MAJOR של TensorFlow (כגון 1.7 עד 2.0 ). בנוסף, תאימות קדימה נאכפת בתוך מהדורות תיקון ( 1.x.1 עד 1.x.2 למשל).

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

תוכניות גרסת נתונים עצמאיות

קיימות גרסאות נתונים שונות עבור גרפים ונקודות ביקורת. שני פורמטי הנתונים מתפתחים בקצב שונה זה מזה וגם בקצב שונה מ- TensorFlow. שתי מערכות הגירסאות מוגדרות ב- core/public/version.h . בכל פעם שנוספת גרסה חדשה, הכותרת מוסיפה הערה המפרטת מה השתנה ואת התאריך.

נתונים, מפיקים וצרכנים

אנו מבחינים בין הסוגים הבאים של מידע על גרסת הנתונים:

• מפיקים : בינאריות שמפיקות נתונים. producer יש גרסה ( producer ) וגרסת צריכה מינימלית שהם תואמים לה ( min_consumer ).
• צרכנים : בינאריות הצורכות נתונים. לצרכנים יש גרסה ( consumer ) וגרסת יצרן מינימלית שהם תואמים לה ( min_producer ).

לכל פיסת נתונים עם VersionDef versions שדה VersionDef versions אשר מתעד את producer שיצר את הנתונים, את min_consumer שאליו הם תואמים, ורשימת גרסאות bad_consumers של bad_consumers שאינן מורשות.

כברירת מחדל, כאשר מפיק מייצר נתונים כלשהם, הנתונים יורשים את גרסאות producer ואת גרסאות min_consumer . ניתן להגדיר צרכנים bad_consumers אם ידוע כי גרסאות צרכניות ספציפיות מכילות באגים ויש להימנע מהן. צרכן יכול לקבל פיסת נתונים אם הדברים הבאים נכונים:

• consumer > = min_consumer של הנתונים
• producer הנתונים> = producer min_producer של הצרכן
• consumer לא 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 כלשהן. סוג זה של שינוי תואם אוטומטית לאחור ואינו משפיע על תוכנית התאימות קדימה מכיוון שסקריפטים מפיקים קיימים לא ישתמשו לפתע בפונקציונליות החדשה.

הוסף אופ והחלף עטיפות פייתון קיימות לשימוש בו

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

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

1. תקן את כל סקריפטי המפיק (לא TensorFlow עצמו) כדי שלא להשתמש ב- OP או בפונקציונליות האסורה.
2. הגדל את גרסת GraphDef פונקציונליות צרכנית חדשה האוסרת על אופציה שהוסרה או פונקציונליות עבור GraphDefs בגרסה החדשה ומעלה. אם אפשר, הפוך את TensorFlow להפסיק לייצר GraphDefs עם הפונקציונליות האסורה. לשם כך, הוסף את REGISTER_OP(...).Deprecated(deprecated_at_version, message) .
3. המתן לשחרור מרכזי למטרות תאימות לאחור.
4. גדל min_producer לגרסת GraphDef מ (2) ולהסיר את הפונקציונליות לחלוטין.

שנה את הפונקציונליות של אופ

1. הוסף אופציה דומה חדשה בשם SomethingV2 או דומה ועברה את תהליך הוספתה והחלפת עטיפות פייתון קיימות לשימוש בה. כדי להבטיח תאימות קדימה השתמש בבדיקות המוצעות ב- compat.py בעת שינוי עטיפות הפייתון.
2. הסר את ה- op הישן (יכול להתקיים רק עם שינוי גרסה משמעותי בגלל תאימות לאחור).
3. הגדל את min_consumer כדי לשלול צרכנים עם ה- OP הישן, הוסף בחזרה את ה- OP הישן ככינוי ל- SomethingV2 ועבר את התהליך להחלפת עטיפות פיתון קיימות לשימוש בו.
4. עברו את התהליך להסרת SomethingV2 .

אסור גרסה צרכנית לא בטוחה אחת

1. GraphDef את גרסת GraphDef והוסף את הגרסה הרעה ל- bad_consumers עבור כל GraphDefs החדשים. אם אפשר, הוסף bad_consumers רק עבור GraphDefs המכילים אופציה מסוימת או דומה.
2. אם לצרכנים קיימים יש את הגרסה הגרועה, דחף אותם החוצה בהקדם האפשרי.