ניהול גרסאות של מערכי נתונים

הַגדָרָה

גירסאות יכולות להתייחס למשמעות שונה:

• גרסת ה-API של TFDS (גרסת pip): tfds. version
• גרסת הנתונים הציבוריים, בלתי תלויה ב-TFDS (למשל Voc2007 , Voc2012). ב-TFDS יש ליישם כל גרסת מערך נתונים ציבורית כמערך נתונים עצמאי:
  • או דרך תצורות בונה : למשל voc/2007 , voc/2012
  • או כ-2 מערכי נתונים עצמאיים: למשל wmt13_translate , wmt14_translate
• גרסת קוד יצירת מערך הנתונים ב-TFDS ( my_dataset:1.0.0 ): לדוגמה, אם נמצא באג ביישום TFDS של voc/2007 , קוד היצירה של voc.py יעודכן ( voc/2007:1.0.0 - > voc/2007:2.0.0 ).

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

גרסאות נתמכות

ככלל:

• ניתן ליצור רק את הגרסה הנוכחית האחרונה.
• ניתן לקרוא את כל הנתונים שנוצרו בעבר (הערה: זה דורש מערכי נתונים שנוצרו עם TFDS 4+).

builder = tfds.builder('my_dataset')
builder.info.version  # Current version is: '2.0.0'

# download and load the last available version (2.0.0)
ds = tfds.load('my_dataset')

# Explicitly load a previous version (only works if
# `~/tensorflow_datasets/my_dataset/1.0.0/` already exists)
ds = tfds.load('my_dataset:1.0.0')

סֵמַנטִי

כל DatasetBuilder המוגדר ב-TFDS מגיע עם גרסה, למשל:

class MNIST(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version('2.0.0')
  RELEASE_NOTES = {
      '1.0.0': 'Initial release',
      '2.0.0': 'Update dead download url',
  }

הגרסה עוקבת אחר גרסה סמנטית 2.0.0 : MAJOR.MINOR.PATCH . מטרת הגרסה היא להיות מסוגל להבטיח יכולת שחזור: טעינת מערך נתונים נתון בגרסה קבועה מניבה את אותם נתונים. ליתר דיוק:

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

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

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

שים לב גם שלמערכי נתונים מסוימים יש סכימת גירסאות אחרת שאינה תלויה בגרסת TFDS. לדוגמה, למערך הנתונים של Open Images יש כמה גרסאות, וב-TFDS, הבונים המתאימים הם open_images_v4 , open_images_v5 , ...

טוען גרסה ספציפית

בעת טעינת מערך נתונים או DatasetBuilder , אתה יכול לציין את הגרסה לשימוש. לְדוּגמָה:

tfds.load('imagenet2012:2.0.1')
tfds.builder('imagenet2012:2.0.1')

tfds.load('imagenet2012:2.0.0')  # Error: unsupported version.

# Resolves to 3.0.0 for now, but would resolve to 3.1.1 if when added.
tfds.load('imagenet2012:3.*.*')

אם אתה משתמש ב-TFDS עבור פרסום, אנו ממליצים לך:

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

פעולה זו אמורה להקל על העצמי העתידי שלך, על הקוראים והסוקרים שלך לשחזר את התוצאות שלך.

BUILDER_CONFIGS וגרסאות

מערכי נתונים מסוימים מגדירים מספר BUILDER_CONFIGS . כאשר זה המקרה, version ו- supported_versions מוגדרות על אובייקטי התצורה עצמם. מלבד זאת, הסמנטיקה והשימוש זהים. לְדוּגמָה:

class OpenImagesV4(tfds.core.GeneratorBasedBuilder):

  BUILDER_CONFIGS = [
      OpenImagesV4Config(
          name='original',
          version=tfds.core.Version('0.2.0'),
          supported_versions=[
            tfds.core.Version('1.0.0', "Major change in data"),
          ],
          description='Images at their original resolution and quality.'),
      ...
  ]

tfds.load('open_images_v4/original:1.*.*')

גרסה נסיונית

אפשר לאפשר יצירת 2 גרסאות בו זמנית. ברירת מחדל אחת וגרסה ניסיונית אחת. לְדוּגמָה:

class MNIST(tfds.core.GeneratorBasedBuilder):
  VERSION = tfds.core.Version("1.0.0")  # Default version
  SUPPORTED_VERSIONS = [
      tfds.core.Version("2.0.0"),  # Experimental version
  ]


# Download and load default version 1.0.0
builder = tfds.builder('mnist')

#  Download and load experimental version 2.0.0
builder = tfds.builder('mnist', version='experimental_latest')

בקוד, עליך להקפיד לתמוך ב-2 הגרסאות:

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

  def _generate_examples(self, path):
    if self.info.version >= '2.0.0':
      ...
    else:
      ...