Phiên bản bộ dữ liệu

Sự định nghĩa

Phiên bản có thể đề cập đến ý nghĩa khác nhau:

  • Phiên bản API TFDS (phiên bản pip): tfds. version
  • Phiên bản tập dữ liệu công khai, độc lập với TFDS (ví dụ Voc2007 , Voc2012). Trong TFDS, mỗi phiên bản tập dữ liệu công khai phải được triển khai dưới dạng tập dữ liệu độc lập:
    • Hoặc thông qua cấu hình trình tạo : Ví dụ voc/2007 , voc/2012
    • Hoặc là 2 bộ dữ liệu độc lập: Ví dụ: wmt13_translate , wmt14_translate
  • Phiên bản mã tạo tập dữ liệu trong TFDS ( my_dataset:1.0.0 ): Ví dụ: nếu tìm thấy lỗi trong quá trình triển khai TFDS của voc/2007 , mã tạo voc.py sẽ được cập nhật ( voc/2007:1.0.0 - > voc/2007:2.0.0 ).

Phần còn lại của hướng dẫn này chỉ tập trung vào định nghĩa cuối cùng (phiên bản mã tập dữ liệu trong kho TFDS).

Phiên bản được hỗ trợ

Theo nguyên tắc chung:

  • Chỉ có thể tạo phiên bản hiện tại cuối cùng.
  • Có thể đọc được tất cả tập dữ liệu được tạo trước đó (lưu ý: Điều này yêu cầu các tập dữ liệu được tạo bằng 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')

Ngữ nghĩa

Mỗi DatasetBuilder được xác định trong TFDS đều có một phiên bản, ví dụ:

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

Phiên bản tuân theo Phiên bản ngữ nghĩa 2.0.0 : MAJOR.MINOR.PATCH . Mục đích của phiên bản là có thể đảm bảo khả năng tái tạo: tải một tập dữ liệu nhất định ở một phiên bản cố định mang lại cùng một dữ liệu. Cụ thể hơn:

  • Nếu phiên bản PATCH được tăng lên, dữ liệu mà máy khách đọc sẽ giống nhau, mặc dù dữ liệu có thể được tuần tự hóa khác nhau trên đĩa hoặc siêu dữ liệu có thể đã thay đổi. Đối với bất kỳ lát cắt cụ thể nào, API cắt lát sẽ trả về cùng một bộ bản ghi.
  • Nếu phiên bản MINOR được tăng lên, dữ liệu hiện có mà máy khách đọc sẽ giống nhau nhưng có dữ liệu bổ sung (các tính năng trong mỗi bản ghi). Đối với bất kỳ lát cắt cụ thể nào, API cắt lát sẽ trả về cùng một bộ bản ghi.
  • Nếu phiên bản MAJOR được tăng lên, dữ liệu hiện có đã được thay đổi và/hoặc API cắt không nhất thiết trả về cùng một bộ bản ghi cho một lát nhất định.

Khi thay đổi mã được thực hiện đối với thư viện TFDS và thay đổi mã đó ảnh hưởng đến cách khách hàng sắp xếp và/hoặc đọc tập dữ liệu, thì phiên bản trình tạo tương ứng sẽ được tăng lên theo các nguyên tắc ở trên.

Lưu ý rằng ngữ nghĩa ở trên là nỗ lực tốt nhất và có thể có những lỗi không được chú ý ảnh hưởng đến tập dữ liệu trong khi phiên bản không được tăng lên. Những lỗi như vậy cuối cùng đã được khắc phục, nhưng nếu bạn phụ thuộc nhiều vào việc lập phiên bản, chúng tôi khuyên bạn nên sử dụng TFDS từ phiên bản đã phát hành (ngược lại với HEAD ).

Cũng lưu ý rằng một số bộ dữ liệu có sơ đồ phiên bản khác độc lập với phiên bản TFDS. Ví dụ: tập dữ liệu Open Images có một số phiên bản và trong TFDS, các trình tạo tương ứng là open_images_v4 , open_images_v5 , ...

Đang tải một phiên bản cụ thể

Khi tải tập dữ liệu hoặc DatasetBuilder , bạn có thể chỉ định phiên bản sẽ sử dụng. Ví dụ:

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

Nếu sử dụng TFDS cho một ấn phẩm, chúng tôi khuyên bạn nên:

  • chỉ sửa thành phần MAJOR của phiên bản ;
  • quảng cáo phiên bản nào của tập dữ liệu đã được sử dụng trong kết quả của bạn.

Làm như vậy sẽ giúp bản thân bạn, người đọc và người đánh giá trong tương lai của bạn dễ dàng tái tạo kết quả của bạn hơn.

BUILDER_CONFIGS và các phiên bản

Một số bộ dữ liệu xác định một số BUILDER_CONFIGS . Trong trường hợp đó, version và supported_versions được xác định trên chính các đối tượng cấu hình. Ngoài ra, ngữ nghĩa và cách sử dụng là giống hệt nhau. Ví dụ: 

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

Phiên bản thử nghiệm

Có thể cho phép tạo 2 phiên bản cùng một lúc. Một phiên bản mặc định và một phiên bản thử nghiệm. Ví dụ:

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

Trong mã, bạn cần đảm bảo hỗ trợ 2 phiên bản:

class MNIST(tfds.core.GeneratorBasedBuilder):

  ...

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