フォーマット固有のデータセット ビルダー

このガイドでは、TFDS で現在利用可能なすべての形式固有のデータセット ビルダーについて説明します。

形式固有のデータセット ビルダーは、特定のデータ形式のほとんどのデータ処理を処理するtfds.core.GeneratorBasedBuilderのサブクラスです。

tf.data.Datasetに基づくデータセット

tf.data.Dataset (参照) 形式のデータセットから TFDS データセットを作成する場合は、 tfds.dataset_builders.TfDataBuilderを使用できます ( API ドキュメントを参照)。

このクラスの典型的な使用法としては、次の 2 つが考えられます。

  • ノートブックのような環境で実験データセットを作成する
  • コードでのデータセット ビルダーの定義

ノートブックから新しいデータセットを作成する

ノートブックで作業しており、データを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_dirtfds.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 🥐 は、メタデータ、リソース ファイルの説明、データ構造、デフォルトの ML セマンティクスを 1 つのファイルに結合する機械学習データセットの高レベル形式です。既存のデータセットと連携して、ツールによる検索、使用、サポートが容易になります。

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 形式のデータには、通常、1 行に 1 つのトークンとその言語注釈が含まれています。同じ行内では、通常、注釈はスペースまたはタブで区切られます。空行は文の境界を表します。

例として、CoNLL アノテーション形式に従っているconll2003データセットの次の文を考えてみましょう。

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メソッドをさらに上書きする必要はありません。

CoNLL 固有のデータセット ビルダーを使用して実装されたデータセットの例としてconll2003を考えてみましょう。

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 形式のデータには、通常、1 行に 1 つのトークンとその言語注釈が含まれています。同じ行内では、通常、注釈は単一のタブ文字で区切られます。空行は文の境界を表します。

通常、公式ドキュメントで報告されているように、各 CoNLL-U アノテーション付きワード行には次のフィールドが含まれます。

  • ID: 単語インデックス。新しい文ごとに 1 から始まる整数。マルチワードトークンの範囲である場合があります。空のノードの場合は 10 進数を指定できます (10 進数は 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 、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 固有のデータセット ビルダーを使用する次のデータセットを考えてみましょう。

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