מסמך זה מיועד למשתמשים הזקוקים לתאימות לאחור בגרסאות שונות של 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 .
קבצי מאגר הפרוטוקול הבאים:
מה אינו מכוסה
חלקים מסוימים של TensorFlow יכולים להשתנות בדרכים לא תואמות לאחור בכל נקודה. אלו כוללים:
ממשקי API ניסיוניים: כדי להקל על פיתוח, אנו לפטור כמה סימני API המסומנים בבירור כניסוי מערבויות התאימות. בפרט, הדברים הבאים אינם מכוסים על ידי ערבויות תאימות כלשהן:
- כל סמל של
tf.contrib
מודול או submodules שלה; - כל סמל (מודול, פונקציה, טיעון, רכוש, מעמד, או קבוע) ששמו מכיל
experimental
אוExperimental
; אוֹ - כל סמל ששמו המלא כולל מודול או מחלקה שהם עצמם ניסיוניים. זה כולל שדות submessages של כל חיץ פרוטוקול שנקרא
experimental
.
- כל סמל של
שפות אחרות: APIs TensorFlow בשפות שאינן Python ו- C, כגון:
- C ++ (חשוף באמצעות קבצי הכותרת
tensorflow/cc
). - Java ,
- ללכת
- JavaScript
- C ++ (חשוף באמצעות קבצי הכותרת
פרטים של חיילים מיחידות מרוכבים: פונקציות ציבוריות רבות 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.
- 1.2 TensorFlow עשוי לתמוך
לבסוף, כאשר תמיכת 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
.
הוסף תכונה חדשה עם ברירת מחדל לאופציה קיימת
ביצוע ההנחיות שלהלן נותן לך תאימות קדימה רק אם ערכת הפעולות לא השתנתה:
- אם תאימות קדימה הוא הרצוי, להגדיר
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
גרסאות. סוג זה של שינוי תואם אוטומטית לאחור ואינו משפיע על תוכנית התאימות קדימה מכיוון שסקריפטים קיימים של מפיק לא ישתמשו לפתע בפונקציונליות החדשה.
הוסף הפעלה והחלף עטיפות Python קיימות כדי להשתמש בה
- ליישם פונקציונליות צרכן חדשות להגדיל את
GraphDef
הגרסה. - אם אפשר לגרום לעוטפים להשתמש בפונקציונליות החדשה רק במקרים שלא עבדו קודם, ניתן לעדכן את העטיפות כבר עכשיו.
- שנה את עטיפות Python כדי להשתמש בפונקציונליות החדשה. האם לא תוספת
min_consumer
, שכן מדובר במודלים שאינם משתמשים op זה לא צריך לשבור.
הסר או הגבל את הפונקציונליות של מבצע
- תקן את כל התסריטים של המפיק (לא 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 אשר מכילים אופ מסוים או דומה. - אם לצרכנים קיימים יש את הגרסה הגרועה, דחוף אותם החוצה בהקדם האפשרי.