Конструкторы наборов данных для конкретного формата

В этом руководстве описаны все построители наборов данных для конкретных форматов, доступные в настоящее время в TFDS.

Построители наборов данных для конкретного формата являются подклассами tfds.core.GeneratorBasedBuilder , которые берут на себя большую часть обработки данных для определенного формата данных.

Наборы данных на основе tf.data.Dataset

Если вы хотите создать набор данных TFDS из набора данных в формате tf.data.Dataset ( ссылка ), вы можете использовать tfds.dataset_builders.TfDataBuilder (см. документацию API ).

Мы предполагаем два типичных использования этого класса:

  • Создание экспериментальных наборов данных в среде, похожей на блокнот
  • Определение построителя набора данных в коде

Создание нового набора данных из блокнота

Предположим, вы работаете в блокноте, загрузили некоторые данные в виде tf.data.Dataset , применили различные преобразования (карта, фильтр и т. д.) и теперь хотите сохранить эти данные и легко поделиться ими с товарищами по команде или загрузить их в другие блокноты. Вместо того, чтобы определять новый класс построителя набора данных, вы также можете создать экземпляр tfds.dataset_builders.TfDataBuilder и вызвать 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 и сохранять соответствующий набор данных TFDS в /my/folder/my_dataset/single_number/1.0.0 , который будет содержать как поездное, так и тестовое разделение.

Аргумент config не является обязательным и может быть полезен, если вы хотите хранить разные конфигурации в одном наборе данных.

Аргумент data_dir можно использовать для хранения сгенерированного набора данных TFDS в другой папке, например, в вашей собственной песочнице, если вы не хотите делиться этим с другими (пока). Обратите внимание: при этом вам также необходимо передать data_dir в tfds.load . Если аргумент data_dir не указан, будет использоваться каталог данных TFDS по умолчанию.

Загрузка набора данных

После сохранения набора данных 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!",
        })

КруассанСтроитель

Формат

Croissant 🥐 — это формат высокого уровня для наборов данных машинного обучения, который объединяет метаданные, описания файлов ресурсов, структуру данных и семантику машинного обучения по умолчанию в один файл; он работает с существующими наборами данных, упрощая их поиск, использование и поддержку с помощью инструментов.

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 обычно содержат один токен с лингвистическими аннотациями в каждой строке; в одной строке аннотации обычно разделяются пробелами или табуляцией. Пустые строки обозначают границы предложения.

Рассмотрим в качестве примера следующее предложение из набора данных 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.

интерфейс командной строки

Самый простой способ написать новый набор данных на основе CoNLL — использовать CLI TFDS : 

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, добавляя ряд функций, таких как поддержка слов, состоящих из нескольких токенов . Данные в формате CoNLL-U обычно содержат один токен с лингвистическими аннотациями в каждой строке; в одной строке аннотации обычно разделяются одиночными символами табуляции. Пустые строки обозначают границы предложения.

Обычно каждая строка аннотированного слова CoNLL-U содержит следующие поля, как сообщается в официальной документации :

  • ID: индекс слова, целое число, начиная с 1 для каждого нового предложения; может быть диапазоном токенов из нескольких слов; может быть десятичным числом для пустых узлов (десятичные числа могут быть меньше 1, но должны быть больше 0).
  • ФОРМА: Словоформа или знак препинания.
  • ЛЕММА: Лемма или основа словоформы.
  • UPOS: Универсальный тег части речи.
  • XPOS: тег части речи для конкретного языка; подчеркните, если недоступно.
  • ФУНКЦИИ: Список морфологических функций из универсального списка функций или из определенного расширения для конкретного языка; подчеркните, если недоступно.
  • HEAD: заголовок текущего слова, который имеет либо значение ID, либо ноль (0).
  • DEPREL: универсальное отношение зависимости к HEAD (корень, если HEAD = 0) или к определенному подтипу, зависящему от языка.
  • DEPS: расширенный граф зависимостей в виде списка пар голова-депрел.
  • РАЗНОЕ: Любая другая аннотация.

Рассмотрим в качестве примера следующее аннотированное предложение 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. Обратитесь к следующему классу как к минимальному примеру построителя набора данных CoNLL-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 (см. пример daset xtreme_pos ).

Примеры

В качестве примеров рассмотрим следующие наборы данных, в которых используется специальный конструктор наборов данных CoNNL-U:

интерфейс командной строки

Самый простой способ написать новый набор данных на основе CoNLL-U — использовать CLI TFDS :

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