特定格式数据集构建器

本指南介绍了 TFDS 中当前可用的所有特定格式数据集构建器。

特定格式数据集构建器是 tfds.core.GeneratorBasedBuilder 的子类，它负责处理特定数据格式的大部分数据处理。

基于 tf.data.Dataset 的数据集

如果您想从 tf.data.Dataset (参考) 格式的数据集中创建 TFDS 数据集，那么您可以使用 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!",
        })

CroissantBuilder

格式

Croissant 🥐 是一种用于机器学习数据集的高级格式，它将元数据、资源文件描述、数据结构和默认 ML 语义组合到一个文件中；它与现有数据集一起使用，使它们更容易查找、使用和支持工具。

Croissant 基于 schema.org 及其 sc:Dataset 词汇表，这是一种广泛用于在 Web 上表示数据集并使其可搜索的格式。

CroissantBuilder

一个 CroissantBuilder 定义了一个基于 Croissant 🥐 元数据文件的 TFDS 数据集；每个指定的 record_set_ids 将导致一个单独的 ConfigBuilder。

例如，要使用其 Croissant 🥐 定义 初始化 MNIST 数据集的 CroissantBuilder

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 实现了一个特定于 CoNLL 的 GeneratorBasedBuilder。将以下类作为 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：以头部-依存关系对列表形式表示的增强依存关系图。
• 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 实现了一个特定于 CoNLL-U 的 GeneratorBasedBuilder。以下类作为 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 方法不需要进一步覆盖。请注意，如果您的数据集需要特定预处理 - 例如，如果它考虑非经典的 通用依存关系特征 - 您可能需要更新 generate_examples 函数的 process_example_fn 属性（以 xtreme_pos 数据集为例）。

示例

以下数据集使用 CoNNL-U 特定数据集构建器作为示例

• universal_dependencies
• xtreme_pos

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