سازندگان مجموعه داده با فرمت خاص

این راهنما تمام سازندگان مجموعه داده های فرمت خاص را که در حال حاضر در TFDS موجود هستند، مستند می کند.

سازندگان مجموعه داده های فرمت خاص، زیر کلاس های tfds.core.GeneratorBasedBuilder هستند که بیشتر پردازش داده ها را برای یک قالب داده خاص انجام می دهند.

مجموعه داده ها بر اساس tf.data.Dataset

اگر می خواهید یک مجموعه داده TFDS از مجموعه داده ای ایجاد کنید که در قالب tf.data.Dataset ( مرجع ) است، می توانید از tfds.dataset_builders.TfDataBuilder استفاده کنید (به اسناد API مراجعه کنید).

ما دو کاربرد معمولی از این کلاس را در نظر می گیریم:

  • ایجاد مجموعه داده های آزمایشی در محیطی شبیه نوت بوک
  • تعریف سازنده مجموعه داده در کد

ایجاد یک مجموعه داده جدید از یک نوت بوک

فرض کنید در یک نوت بوک کار می کنید، برخی از داده ها را به عنوان tf.data.Dataset بارگذاری کرده اید، تبدیل های مختلف (نقشه، فیلتر و غیره) را اعمال کرده اید و اکنون می خواهید این داده ها را ذخیره کنید و به راحتی آن را با هم تیمی ها به اشتراک بگذارید یا در نوت بوک های دیگر بارگذاری کنید. به جای اینکه یک کلاس سازنده مجموعه داده جدید تعریف کنید، می‌توانید یک tfds.dataset_builders.TfDataBuilder را نیز نمونه‌سازی کنید و با call download_and_prepare ، مجموعه داده‌های خود را به عنوان مجموعه داده TFDS ذخیره کنید.

از آنجایی که این یک مجموعه داده TFDS است، می‌توانید آن را نسخه کنید، از تنظیمات استفاده کنید، تقسیم‌بندی‌های مختلف داشته باشید و برای استفاده آسان‌تر بعداً آن را مستند کنید. این بدان معنی است که شما همچنین باید به TFDS بگویید که چه ویژگی هایی در مجموعه داده شما وجود دارد.

در اینجا یک مثال ساختگی از نحوه استفاده از آن آورده شده است.

import tensorflow as tf
import tensorflow_datasets as tfds

my_ds_train = tf.data.Dataset.from_tensor_slices({"number": [1, 2, 3]})
my_ds_test = tf.data.Dataset.from_tensor_slices({"number": [4, 5]})

# Optionally define a custom `data_dir`.
# If None, then the default data dir is used.
custom_data_dir = "/my/folder"

# Define the builder.
single_number_builder = tfds.dataset_builders.TfDataBuilder(
    name="my_dataset",
    config="single_number",
    version="1.0.0",
    data_dir=custom_data_dir,
    split_datasets={
        "train": my_ds_train,
        "test": my_ds_test,
    },
    features=tfds.features.FeaturesDict({
        "number": tfds.features.Scalar(dtype=tf.int64),
    }),
    description="My dataset with a single number.",
    release_notes={
        "1.0.0": "Initial release with numbers up to 5!",
    }
)

# Make the builder store the data as a TFDS dataset.
single_number_builder.download_and_prepare()

روش download_and_prepare روی ورودی tf.data.Dataset s تکرار می‌شود و مجموعه داده TFDS مربوطه را در /my/folder/my_dataset/single_number/1.0.0 ذخیره می‌کند، که شامل هر دو تقسیم قطار و آزمایش است.

آرگومان config اختیاری است و اگر می‌خواهید پیکربندی‌های مختلف را در یک مجموعه داده ذخیره کنید، می‌تواند مفید باشد.

آرگومان data_dir می تواند برای ذخیره مجموعه داده های TFDS تولید شده در یک پوشه دیگر استفاده شود، برای مثال اگر نمی خواهید آن را با دیگران به اشتراک بگذارید (هنوز). توجه داشته باشید که هنگام انجام این کار، باید data_dir نیز به tfds.load ارسال کنید. اگر آرگومان data_dir مشخص نشده باشد، از پیش‌فرض داده‌های TFDS dir استفاده می‌شود.

در حال بارگیری مجموعه داده شما

پس از اینکه مجموعه داده TFDS ذخیره شد، می توان آن را از اسکریپت های دیگر یا توسط هم تیمی ها در صورت دسترسی به داده ها بارگیری کرد:

# If no custom data dir was specified:
ds_test = tfds.load("my_dataset/single_number", split="test")

# When there are multiple versions, you can also specify the version.
ds_test = tfds.load("my_dataset/single_number:1.0.0", split="test")

# If the TFDS was stored in a custom folder, then it can be loaded as follows:
custom_data_dir = "/my/folder"
ds_test = tfds.load("my_dataset/single_number:1.0.0", split="test", data_dir=custom_data_dir)

افزودن نسخه یا پیکربندی جدید

پس از تکرار بیشتر در مجموعه داده خود، ممکن است برخی از تغییرات داده های منبع را اضافه کرده یا تغییر داده باشید. برای ذخیره و اشتراک گذاری این مجموعه داده، می توانید به راحتی آن را به عنوان یک نسخه جدید ذخیره کنید.

def add_one(example):
  example["number"] = example["number"] + 1
  return example

my_ds_train_v2 = my_ds_train.map(add_one)
my_ds_test_v2 = my_ds_test.map(add_one)

single_number_builder_v2 = tfds.dataset_builders.TfDataBuilder(
    name="my_dataset",
    config="single_number",
    version="1.1.0",
    data_dir=custom_data_dir,
    split_datasets={
        "train": my_ds_train_v2,
        "test": my_ds_test_v2,
    },
    features=tfds.features.FeaturesDict({
        "number": tfds.features.Scalar(dtype=tf.int64, doc="Some number"),
    }),
    description="My dataset with a single number.",
    release_notes={
        "1.1.0": "Initial release with numbers up to 6!",
        "1.0.0": "Initial release with numbers up to 5!",
    }
)

# Make the builder store the data as a TFDS dataset.
single_number_builder_v2.download_and_prepare()

تعریف یک کلاس سازنده مجموعه داده جدید

همچنین می توانید یک DatasetBuilder جدید بر اساس این کلاس تعریف کنید.

import tensorflow as tf
import tensorflow_datasets as tfds

class MyDatasetBuilder(tfds.dataset_builders.TfDataBuilder):
  def __init__(self):
    ds_train = tf.data.Dataset.from_tensor_slices([1, 2, 3])
    ds_test = tf.data.Dataset.from_tensor_slices([4, 5])
    super().__init__(
        name="my_dataset",
        version="1.0.0",
        split_datasets={
            "train": ds_train,
            "test": ds_test,
        },
        features=tfds.features.FeaturesDict({
            "number": tfds.features.Scalar(dtype=tf.int64),
        }),
        config="single_number",
        description="My dataset with a single number.",
        release_notes={
            "1.0.0": "Initial release with numbers up to 5!",
        })

CroissantBuilder

قالب

Croissant 🥐 قالبی سطح بالا برای مجموعه داده های یادگیری ماشینی است که ابرداده ها، توضیحات فایل منابع، ساختار داده و معنای پیش فرض ML را در یک فایل واحد ترکیب می کند. با مجموعه داده‌های موجود کار می‌کند تا یافتن، استفاده و پشتیبانی با ابزارها را آسان‌تر کند.

Croissant بر روی schema.org و واژگان sc:Dataset آن، قالبی پرکاربرد برای نمایش مجموعه داده‌ها در وب و قابل جستجو کردن آن‌ها ساخته شده است.

CroissantBuilder

یک CroissantBuilder یک مجموعه داده TFDS را بر اساس یک فایل فراداده Croissant 🥐 تعریف می کند. هر یک از record_set_ids مشخص شده منجر به یک ConfigBuilder جداگانه می شود.

به عنوان مثال، برای مقداردهی اولیه یک CroissantBuilder برای مجموعه داده MNIST با استفاده از تعریف Croissant 🥐 آن:

import tensorflow_datasets as tfds
builder = tfds.dataset_builders.CroissantBuilder(
    jsonld="https://raw.githubusercontent.com/mlcommons/croissant/main/datasets/0.8/huggingface-mnist/metadata.json",
    file_format='array_record',
)
builder.download_and_prepare()
ds = builder.as_data_source()
print(ds['default'][0])

CoNLL

قالب

CoNLL یک فرمت محبوب است که برای نمایش داده های متنی حاشیه نویسی استفاده می شود.

داده‌های قالب‌بندی‌شده با CoNLL معمولاً حاوی یک نشانه با حاشیه‌نویسی‌های زبانی در هر خط هستند. در همان خط، حاشیه نویسی ها معمولاً با فاصله یا برگه ها از هم جدا می شوند. خطوط خالی مرزهای جمله را نشان می دهند.

به عنوان مثال جمله زیر را از مجموعه داده conll2003 در نظر بگیرید که از قالب حاشیه نویسی CoNLL پیروی می کند:

U.N. NNP I-NP I-ORG official
NN I-NP O
Ekeus NNP I-NP I-PER
heads VBZ I-VP O
for IN I-PP O
Baghdad NNP I-NP
I-LOC . . O O

ConllDatasetBuilder

برای افزودن یک مجموعه داده جدید مبتنی بر CoNLL به TFDS، می‌توانید کلاس سازنده مجموعه خود را بر پایه tfds.dataset_builders.ConllDatasetBuilder قرار دهید. این کلاس پایه حاوی کدهای رایج برای رسیدگی به ویژگی های مجموعه داده های CoNLL است (تکرار در قالب ستونی، لیست های از پیش کامپایل شده ویژگی ها و برچسب ها، ...).

tfds.dataset_builders.ConllDatasetBuilder یک GeneratorBasedBuilder مخصوص CoNLL را پیاده سازی می کند. به کلاس زیر به عنوان نمونه حداقلی از سازنده مجموعه داده های CoNLL مراجعه کنید:

from tensorflow_datasets.core.dataset_builders.conll import conll_dataset_builder_utils as conll_lib
import tensorflow_datasets.public_api as tfds

class MyCoNNLDataset(tfds.dataset_builders.ConllDatasetBuilder):
  VERSION = tfds.core.Version('1.0.0')
  RELEASE_NOTES = {'1.0.0': 'Initial release.'}

  # conllu_lib contains a set of ready-to-use CONLL-specific configs.
  BUILDER_CONFIGS = [conll_lib.CONLL_2003_CONFIG]

  def _info(self) -> tfds.core.DatasetInfo:
    return self.create_dataset_info(
        # ...
    )

  def _split_generators(self, dl_manager):
    path = dl_manager.download_and_extract('https://data-url')

    return {'train': self._generate_examples(path=path / 'train.txt'),
            'test': self._generate_examples(path=path / 'train.txt'),
    }

در مورد سازندگان مجموعه داده استاندارد، باید متدهای کلاس _info و _split_generators را بازنویسی کرد. بسته به مجموعه داده، ممکن است لازم باشد conll_dataset_builder_utils.py را نیز به‌روزرسانی کنید تا ویژگی‌ها و فهرست برچسب‌های مختص مجموعه داده‌تان را در بر بگیرد.

روش _generate_examples نباید نیاز به بازنویسی بیشتری داشته باشد، مگر اینکه مجموعه داده شما به پیاده سازی خاصی نیاز داشته باشد.

نمونه ها

conll2003 را به عنوان نمونه ای از مجموعه داده ای در نظر بگیرید که با استفاده از سازنده مجموعه داده های خاص CoNLL پیاده سازی شده است.

CLI

ساده ترین راه برای نوشتن یک مجموعه داده جدید مبتنی بر CoNLL استفاده از TFDS CLI است:

cd path/to/my/project/datasets/
tfds new my_dataset --format=conll   # Create `my_dataset/my_dataset.py` CoNLL-specific template files

CoNLL-U

قالب

CoNLL-U یک فرمت محبوب است که برای نمایش داده های متنی حاشیه نویسی استفاده می شود.

CoNLL-U با افزودن تعدادی ویژگی، مانند پشتیبانی از کلمات چند نشانه ای، قالب CoNLL را بهبود می بخشد. داده های قالب بندی شده CoNLL-U معمولاً حاوی یک نشانه با حاشیه نویسی زبانی در هر خط است. در همان خط، حاشیه نویسی ها معمولاً با کاراکترهای تک برگه جدا می شوند. خطوط خالی مرزهای جمله را نشان می دهند.

به طور معمول، هر خط کلمه مشروح شده CoNLL-U حاوی فیلدهای زیر است، همانطور که در اسناد رسمی گزارش شده است:

  • ID: فهرست کلمه، عدد صحیح که از 1 برای هر جمله جدید شروع می شود. ممکن است محدوده ای برای نشانه های چند کلمه ای باشد. ممکن است یک عدد اعشاری برای گره های خالی باشد (اعداد اعشاری می توانند کمتر از 1 باشند اما باید بزرگتر از 0 باشند).
  • FORM: شکل کلمه یا علامت نقطه گذاری.
  • LEMMA: لم یا ریشه شکل کلمه.
  • UPOS: تگ جهانی بخشی از گفتار.
  • XPOS: برچسب قسمت گفتار مخصوص زبان. در صورت موجود نبودن زیر خط بزنید
  • FEATS: فهرست ویژگی‌های مورفولوژیکی از فهرست ویژگی‌های جهانی یا از یک پسوند خاص زبان تعریف شده. در صورت موجود نبودن زیر خط بزنید
  • HEAD: سر کلمه فعلی که یا مقدار ID یا صفر (0) است.
  • DEPREL: رابطه وابستگی جهانی به HEAD (ریشه اگر HEAD = 0) یا یک زیرگروه خاص برای زبان تعریف شده است.
  • DEPS: نمودار وابستگی پیشرفته به شکل لیستی از جفت‌های head-deprel.
  • MISC: هر حاشیه نویسی دیگری.

به عنوان مثال جمله مشروح CoNLL-U زیر را از اسناد رسمی در نظر بگیرید:

1-2    vámonos   _
1      vamos     ir
2      nos       nosotros
3-4    al        _
3      a         a
4      el        el
5      mar       mar

ConllUDatasetBuilder

برای افزودن یک مجموعه داده جدید مبتنی بر CoNLL-U به TFDS، می توانید کلاس سازنده مجموعه داده خود را بر اساس tfds.dataset_builders.ConllUDatasetBuilder قرار دهید. این کلاس پایه حاوی کدهای رایج برای رسیدگی به ویژگی های مجموعه داده های CoNLL-U است (تکرار در قالب ستونی، لیست های از پیش کامپایل شده ویژگی ها و برچسب ها، ...).

tfds.dataset_builders.ConllUDatasetBuilder یک GeneratorBasedBuilder خاص CoNLL-U را پیاده سازی می کند. به کلاس زیر به عنوان نمونه حداقلی از سازنده مجموعه داده ConnLL-U مراجعه کنید:

from tensorflow_datasets.core.dataset_builders.conll import conllu_dataset_builder_utils as conllu_lib
import tensorflow_datasets.public_api as tfds

class MyCoNNLUDataset(tfds.dataset_builders.ConllUDatasetBuilder):
  VERSION = tfds.core.Version('1.0.0')
  RELEASE_NOTES = {'1.0.0': 'Initial release.'}

  # conllu_lib contains a set of ready-to-use features.
  BUILDER_CONFIGS = [
      conllu_lib.get_universal_morphology_config(
          language='en',
          features=conllu_lib.UNIVERSAL_DEPENDENCIES_FEATURES,
      )
  ]

  def _info(self) -> tfds.core.DatasetInfo:
    return self.create_dataset_info(
        # ...
    )

  def _split_generators(self, dl_manager):
    path = dl_manager.download_and_extract('https://data-url')

    return {
        'train':
            self._generate_examples(
                path=path / 'train.txt',
                # If necessary, add optional custom processing (see conllu_lib
                # for examples).
                # process_example_fn=...,
            )
    }

در مورد سازندگان مجموعه داده استاندارد، باید متدهای کلاس _info و _split_generators را بازنویسی کرد. بسته به مجموعه داده، ممکن است لازم باشد conllu_dataset_builder_utils.py را نیز به‌روزرسانی کنید تا ویژگی‌ها و فهرست برچسب‌های مختص مجموعه داده‌تان را در بر بگیرد.

روش _generate_examples نباید نیاز به بازنویسی بیشتری داشته باشد، مگر اینکه مجموعه داده شما به پیاده سازی خاصی نیاز داشته باشد. توجه داشته باشید که اگر مجموعه داده شما به پیش پردازش خاصی نیاز دارد - برای مثال اگر ویژگی‌های وابستگی جهانی غیرکلاسیک را در نظر می‌گیرد - ممکن است نیاز داشته باشید که ویژگی process_example_fn تابع generate_examples خود را به‌روزرسانی کنید (به‌عنوان مثال xtreme_pos daset را ببینید).

نمونه ها

مجموعه داده های زیر را که از سازنده داده خاص Connl-U استفاده می کنند، به عنوان نمونه در نظر بگیرید:

CLI

ساده ترین راه برای نوشتن یک مجموعه داده جدید مبتنی بر CoNLL-U استفاده از TFDS CLI است:

cd path/to/my/project/datasets/
tfds new my_dataset --format=conllu   # Create `my_dataset/my_dataset.py` CoNLL-U specific template files