Pembuatan versi kumpulan data

Definisi

Pembuatan versi dapat merujuk pada arti yang berbeda:

  • Versi API TFDS (versi pip): tfds. version
  • Versi kumpulan data publik, independen dari TFDS (misalnya Voc2007 , Voc2012). Di TFDS, setiap versi kumpulan data publik harus diimplementasikan sebagai kumpulan data independen:
    • Baik melalui konfigurasi pembuat : Misalnya voc/2007 , voc/2012
    • Baik sebagai 2 kumpulan data independen: Misalnya wmt13_translate , wmt14_translate
  • Versi kode pembuatan kumpulan data di TFDS ( my_dataset:1.0.0 ): Misalnya, jika ditemukan bug dalam implementasi TFDS voc/2007 , kode pembuatan voc.py akan diperbarui ( voc/2007:1.0.0 - > voc/2007:2.0.0 ).

Sisa panduan ini hanya fokus pada definisi terakhir (versi kode kumpulan data di repositori TFDS).

Versi yang didukung

Sebagai aturan umum:

  • Hanya versi terakhir saat ini yang dapat dibuat.
  • Semua kumpulan data yang dibuat sebelumnya dapat dibaca (catatan: Ini memerlukan kumpulan data yang dibuat dengan 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')

Semantik

Setiap DatasetBuilder yang ditentukan di TFDS dilengkapi dengan versinya, misalnya:

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',
  }

Versinya mengikuti Versi Semantik 2.0.0 : MAJOR.MINOR.PATCH . Tujuan dari versi ini adalah untuk menjamin reproduktifitas: memuat kumpulan data tertentu pada versi tetap akan menghasilkan data yang sama. Lebih khusus lagi:

  • Jika versi PATCH bertambah, data yang dibaca oleh klien akan sama, meskipun data mungkin diserialkan secara berbeda pada disk, atau metadatanya mungkin telah berubah. Untuk setiap irisan tertentu, API pemotongan akan mengembalikan kumpulan data yang sama.
  • Jika versi MINOR ditambah maka data yang ada yang dibaca oleh klien sama, namun ada tambahan data (fitur di setiap record). Untuk setiap irisan tertentu, API pemotongan akan mengembalikan kumpulan data yang sama.
  • Jika versi MAJOR bertambah, data yang ada telah diubah dan/atau API pemotongan tidak serta merta mengembalikan kumpulan catatan yang sama untuk potongan tertentu.

Ketika perubahan kode dilakukan pada pustaka TFDS dan perubahan kode tersebut berdampak pada cara kumpulan data diserialkan dan/atau dibaca oleh klien, maka versi pembuat yang sesuai akan bertambah sesuai dengan pedoman di atas.

Perhatikan bahwa semantik di atas adalah upaya terbaik, dan mungkin ada bug yang tidak diketahui yang memengaruhi kumpulan data saat versinya tidak bertambah. Bug tersebut pada akhirnya diperbaiki, tetapi jika Anda sangat bergantung pada pembuatan versi, kami menyarankan Anda untuk menggunakan TFDS dari versi yang dirilis (bukan HEAD ).

Perhatikan juga bahwa beberapa kumpulan data memiliki skema pembuatan versi lain yang independen dari versi TFDS. Misalnya, kumpulan data Open Images memiliki beberapa versi, dan di TFDS, pembuat yang sesuai adalah open_images_v4 , open_images_v5 , ...

Memuat versi tertentu

Saat memuat kumpulan data atau DatasetBuilder , Anda dapat menentukan versi yang akan digunakan. Misalnya:

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.*.*')

Jika menggunakan TFDS untuk publikasi, kami menyarankan Anda untuk:

  • memperbaiki komponen MAJOR dari versi saja ;
  • iklankan versi kumpulan data mana yang digunakan dalam hasil Anda.

Melakukan hal ini akan memudahkan Anda, pembaca, dan pengulas di masa depan untuk mereproduksi hasil Anda.

BUILDER_CONFIGS dan versi

Beberapa kumpulan data mendefinisikan beberapa BUILDER_CONFIGS . Jika demikian, version supported_versions ditentukan pada objek konfigurasi itu sendiri. Selain itu, semantik dan penggunaannya identik. Misalnya: 

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.*.*')

Versi eksperimental

Dimungkinkan untuk mengizinkan 2 versi dibuat secara bersamaan. Satu versi default dan satu versi eksperimental. Misalnya:

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')

Dalam kode, Anda perlu memastikan untuk mendukung 2 versi:

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

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