Costruttori di set di dati specifici del formato

Questa guida documenta tutti i costruttori di set di dati specifici del formato attualmente disponibili in TFDS.

I costruttori di set di dati specifici del formato sono sottoclassi di tfds.core.GeneratorBasedBuilder che si occupano della maggior parte dell'elaborazione dei dati per un formato dati specifico.

Set di dati basati su tf.data.Dataset

Se desideri creare un set di dati TFDS da un set di dati in formato tf.data.Dataset ( riferimento ), puoi utilizzare tfds.dataset_builders.TfDataBuilder (vedi documenti API ).

Prevediamo due usi tipici di questa classe:

  • Creazione di set di dati sperimentali in un ambiente simile a un notebook
  • Definizione di un generatore di set di dati nel codice

Creazione di un nuovo set di dati da un notebook

Supponiamo che tu stia lavorando su un notebook, caricato alcuni dati come tf.data.Dataset , applicato varie trasformazioni (mappa, filtro, ecc.) e ora desideri archiviare questi dati e condividerli facilmente con i compagni di squadra o caricarli in altri notebook. Invece di dover definire una nuova classe del generatore di set di dati, puoi anche creare un'istanza di tfds.dataset_builders.TfDataBuilder e chiamare download_and_prepare per archiviare il tuo set di dati come set di dati TFDS.

Poiché si tratta di un set di dati TFDS, puoi modificarne la versione, utilizzare configurazioni, avere suddivisioni diverse e documentarlo per un utilizzo più semplice in seguito. Ciò significa che devi anche dire a TFDS quali sono le funzionalità nel tuo set di dati.

Ecco un esempio fittizio di come puoi usarlo.

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

Il metodo download_and_prepare eseguirà un'iterazione sull'input tf.data.Dataset s e memorizzerà il set di dati TFDS corrispondente in /my/folder/my_dataset/single_number/1.0.0 , che conterrà sia le suddivisioni del treno che quelle del test.

L'argomento config è facoltativo e può essere utile se desideri archiviare configurazioni diverse nello stesso set di dati.

L'argomento data_dir può essere utilizzato per archiviare il set di dati TFDS generato in una cartella diversa, ad esempio nella propria sandbox se non si desidera condividerlo con altri (ancora). Tieni presente che quando lo fai, devi anche passare data_dir a tfds.load . Se l'argomento data_dir non è specificato, verrà utilizzata la directory dei dati TFDS predefinita.

Caricamento del set di dati

Dopo che il set di dati TFDS è stato archiviato, può essere caricato da altri script o dai compagni di squadra se hanno accesso ai dati:

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

Aggiunta di una nuova versione o configurazione

Dopo aver ripetuto ulteriormente il set di dati, potresti aver aggiunto o modificato alcune trasformazioni dei dati di origine. Per archiviare e condividere questo set di dati, puoi facilmente archiviarlo come una nuova versione.

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

Definizione di una nuova classe del generatore di set di dati

Puoi anche definire un nuovo DatasetBuilder basato su questa classe.

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

Il formato

Croissant 🥐 è un formato di alto livello per set di dati di machine learning che combina metadati, descrizioni di file di risorse, struttura dei dati e semantica ML predefinita in un unico file; funziona con i set di dati esistenti per renderli più facili da trovare, utilizzare e supportare con gli strumenti.

Croissant si basa su schema.org e sul suo vocabolario sc:Dataset , un formato ampiamente utilizzato per rappresentare set di dati sul Web e renderli ricercabili.

CroissantBuilder

Un CroissantBuilder definisce un set di dati TFDS basato su un file di metadati Croissant 🥐; ciascuno dei record_set_ids specificati risulterà in un ConfigBuilder separato.

Ad esempio, per inizializzare un CroissantBuilder per il set di dati MNIST utilizzando la definizione 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

Il formato

CoNLL è un formato popolare utilizzato per rappresentare dati di testo annotati.

I dati formattati CoNLL solitamente contengono un token con le relative annotazioni linguistiche per riga; all'interno della stessa riga, le annotazioni sono solitamente separate da spazi o tabulazioni. Le righe vuote rappresentano i confini della frase.

Considera come esempio la seguente frase del set di dati conll2003 , che segue il formato di annotazione 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

Per aggiungere un nuovo set di dati basato su CoNLL a TFDS, puoi basare la classe del generatore di set di dati su tfds.dataset_builders.ConllDatasetBuilder . Questa classe base contiene codice comune per gestire le specificità dei set di dati CoNLL (iterazione sul formato basato su colonne, elenchi precompilati di funzionalità e tag, ...).

tfds.dataset_builders.ConllDatasetBuilder implementa un GeneratorBasedBuilder specifico di CoNLL. Fare riferimento alla seguente classe come esempio minimo di generatore di set di dati 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'),
    }

Per quanto riguarda i costruttori di set di dati standard, è necessario sovrascrivere i metodi della classe _info e _split_generators . A seconda del set di dati, potrebbe essere necessario aggiornare anche conll_dataset_builder_utils.py per includere le funzionalità e l'elenco di tag specifici del tuo set di dati.

Il metodo _generate_examples non dovrebbe richiedere ulteriore sovrascrittura, a meno che il set di dati non richieda un'implementazione specifica.

Esempi

Considera conll2003 come un esempio di set di dati implementato utilizzando il costruttore di set di dati specifico di CoNLL.

CLI

Il modo più semplice per scrivere un nuovo set di dati basato su CoNLL è utilizzare la 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

Il formato

CoNLL-U è un formato popolare utilizzato per rappresentare dati di testo annotati.

CoNLL-U migliora il formato CoNLL aggiungendo una serie di funzionalità, come il supporto per parole multi-token . I dati formattati CoNLL-U contengono solitamente un token con le relative annotazioni linguistiche per riga; all'interno della stessa riga, le annotazioni sono generalmente separate da singoli caratteri di tabulazione. Le righe vuote rappresentano i confini della frase.

Tipicamente, ogni word line annotata CoNLL-U contiene i seguenti campi, come riportato nella documentazione ufficiale :

  • ID: Indice delle parole, intero a partire da 1 per ogni nuova frase; può essere un intervallo per token multiparola; può essere un numero decimale per i nodi vuoti (i numeri decimali possono essere inferiori a 1 ma devono essere maggiori di 0).
  • FORMA: forma della parola o simbolo di punteggiatura.
  • LEMMA: Lemma o radice della parola.
  • UPOS: tag universale della parte del discorso.
  • XPOS: tag della parte del discorso specifica della lingua; sottolineato se non disponibile.
  • CARATTERISTICHE: elenco delle caratteristiche morfologiche dall'inventario delle caratteristiche universali o da un'estensione specifica della lingua definita; sottolineato se non disponibile.
  • HEAD: testa della parola corrente, che può essere un valore ID o zero (0).
  • DEPREL: relazione di dipendenza universale con HEAD (radice sse HEAD = 0) o un sottotipo specifico della lingua definito di uno.
  • DEPS: grafico delle dipendenze migliorato sotto forma di un elenco di coppie testa-deprel.
  • MISC: Qualsiasi altra annotazione.

Considera come esempio la seguente frase annotata CoNLL-U dalla documentazione ufficiale :

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

ConllUDatasetBuilder

Per aggiungere un nuovo set di dati basato su CoNLL-U a TFDS, puoi basare la classe del generatore di set di dati su tfds.dataset_builders.ConllUDatasetBuilder . Questa classe base contiene codice comune per gestire le specificità dei set di dati CoNLL-U (iterazione sul formato basato su colonne, elenchi precompilati di funzionalità e tag, ...).

tfds.dataset_builders.ConllUDatasetBuilder implementa un GeneratorBasedBuilder specifico per CoNLL-U. Fare riferimento alla seguente classe come esempio minimo di generatore di set di dati 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=...,
            )
    }

Per quanto riguarda i costruttori di set di dati standard, è necessario sovrascrivere i metodi della classe _info e _split_generators . A seconda del set di dati, potrebbe essere necessario aggiornare anche conllu_dataset_builder_utils.py per includere le funzionalità e l'elenco di tag specifici del tuo set di dati.

Il metodo _generate_examples non dovrebbe richiedere ulteriore sovrascrittura, a meno che il set di dati non richieda un'implementazione specifica. Tieni presente che, se il tuo set di dati richiede una preelaborazione specifica, ad esempio se considera funzionalità di dipendenza universale non classiche, potresti dover aggiornare l'attributo process_example_fn della tua funzione generate_examples (vedi il daset xtreme_pos come esempio).

Esempi

Considerare come esempi i seguenti set di dati, che utilizzano il costruttore di set di dati specifico CoNNL-U:

CLI

Il modo più semplice per scrivere un nuovo set di dati basato su CoNLL-U è utilizzare la 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