การกำหนดเวอร์ชันชุดข้อมูล

คำนิยาม

การกำหนดเวอร์ชันสามารถอ้างอิงถึงความหมายที่แตกต่างกัน:

  • เวอร์ชัน TFDS API (เวอร์ชัน pip): tfds. version
  • เวอร์ชันชุดข้อมูลสาธารณะ เป็นอิสระจาก TFDS (เช่น Voc2007 , Voc2012) ใน TFDS แต่ละเวอร์ชันชุดข้อมูลสาธารณะควรถูกนำมาใช้เป็นชุดข้อมูลอิสระ:
  • เวอร์ชันของรหัสการสร้างชุดข้อมูลใน 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',
  }

เวอร์ชันเป็นไปตาม Semantic Versioning 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:
      ...