機能コネクタ

tfds.features.FeatureConnector API:

最終的なtf.data.Datasetの構造、形状、dtype を定義します。
ディスクとの間のシリアル化を抽象化します。
追加のメタデータ (ラベル名、オーディオサンプルレートなど) を公開します。

概要

tfds.features.FeatureConnectorデータセットの特徴構造を定義します ( tfds.core.DatasetInfo内)。

tfds.core.DatasetInfo(
    features=tfds.features.FeaturesDict({
        'image': tfds.features.Image(shape=(28, 28, 1), doc='Grayscale image'),
        'label': tfds.features.ClassLabel(
            names=['no', 'yes'],
            doc=tfds.features.Documentation(
                desc='Whether this is a picture of a cat',
                value_range='yes or no'
            ),
        ),
        'metadata': {
            'id': tf.int64,
            'timestamp': tfds.features.Scalar(
                tf.int64,
                doc='Timestamp when this picture was taken as seconds since epoch'),
            'language': tf.string,
        },
    }),
)

機能は、テキストによる説明 ( doc='description' ) のみを使用するか、 tfds.features.Documentationを直接使用してより詳細な機能の説明を提供することによって文書化できます。

特徴は次のとおりです。

スカラー値: tf.bool 、 tf.string 、 tf.float32 、... 機能を文書化したい場合は、 tfds.features.Scalar(tf.int64, doc='description')を使用することもできます。
tfds.features.Audio 、 tfds.features.Video 、... (利用可能な機能のリストを参照)
機能のネストされたdict : {'metadata': {'image': Image(), 'description': tf.string} } ,...
ネストされたtfds.features.Sequence : Sequence({'image': ..., 'id': ...}) 、 Sequence(Sequence(tf.int64)) 、...

生成中に、サンプルは、 FeatureConnector.encode_exampleによってディスクに適した形式に自動的にシリアル化されます (現在はtf.train.Exampleプロトコルバッファー)。

yield {
    'image': '/path/to/img0.png',  # `np.array`, file bytes,... also accepted
    'label': 'yes',  # int (0-num_classes) also accepted
    'metadata': {
        'id': 43,
        'language': 'en',
    },
}

データセットを読み取るとき (たとえば、 tfds.loadを使用)、データはFeatureConnector.decode_exampleを使用して自動的にデコードされます。返されたtf.data.Dataset tfds.core.DatasetInfoで定義されたdict構造と一致します。

ds = tfds.load(...)
ds.element_spec == {
    'image': tf.TensorSpec(shape=(28, 28, 1), tf.uint8),
    'label': tf.TensorSpec(shape=(), tf.int64),
    'metadata': {
        'id': tf.TensorSpec(shape=(), tf.int64),
        'language': tf.TensorSpec(shape=(), tf.string),
    },
}

proto へのシリアル化/逆シリアル化

TFDS は、サンプルをtf.train.Exampleプロトにシリアル化/逆シリアル化するための低レベル API を公開します。

with tf.io.TFRecordWriter('path/to/file.tfrecord') as writer:
  for ex in all_exs:
    ex_bytes = features.serialize_example(data)
    f.write(ex_bytes)

proto bytesからtf.Tensorに逆シリアル化するには、 features.deserialize_exampleを使用します。

ds = tf.data.TFRecordDataset('path/to/file.tfrecord')
ds = ds.map(features.deserialize_example)

メタデータにアクセスする

機能のメタデータ (ラベル名、形状、dtype など) にアクセスするには、概要ドキュメントを参照してください。例：

ds, info = tfds.load(..., with_info=True)

info.features['label'].names  # ['cat', 'dog', ...]
info.features['label'].str2int('cat')  # 0

独自の`tfds.features.FeatureConnector`を作成する

利用可能な機能に不足している機能があると思われる場合は、新しい問題を開いてください。

独自の機能コネクタを作成するには、 tfds.features.FeatureConnectorから継承し、抽象メソッドを実装する必要があります。

特徴が単一のテンソル値である場合は、 tfds.features.Tensorから継承し、必要に応じてsuper()を使用するのが最善です。例については、 tfds.features.BBoxFeatureソースコードを参照してください。
フィーチャが複数のテンソルのコンテナである場合は、 tfds.features.FeaturesDictから継承し、 super()を使用してサブコネクタを自動的にエンコードするのが最善です。

tfds.features.FeatureConnectorオブジェクトは、機能がユーザーに表示される方法からディスク上でエンコードされる方法を抽象化します。以下は、データセットの抽象化レイヤーと、生のデータセットファイルからtf.data.Datasetオブジェクトへの変換を示す図です。

DatasetBuilder 抽象化レイヤー

独自の機能コネクタを作成するには、 tfds.features.FeatureConnectorをサブクラス化し、抽象メソッドを実装します。

encode_example(data) : ジェネレーター_generate_examples()で指定されたデータをtf.train.Exampleと互換性のあるデータにエンコードする方法を定義します。単一の値、または値のdictを返すことができます。
decode_example(data) : tf.train.Exampleから読み取られたテンソルからtf.data.Datasetによって返されたユーザーテンソルにデータをデコードする方法を定義します。
get_tensor_info() : tf.data.Datasetによって返されるテンソルの形状/dtype を示します。別のtfds.featuresから継承する場合はオプションになる可能性があります。
(オプション) get_serialized_info() : get_tensor_info()によって返された情報が、データが実際にディスクに書き込まれる方法と異なる場合は、 tf.train.Exampleの仕様に一致するようにget_serialized_info()を上書きする必要があります。
to_json_content / from_json_content : これは、元のソースコードなしでデータセットをロードできるようにするために必要です。例については、「オーディオ機能」を参照してください。

詳細については、 tfds.features.FeatureConnectorドキュメントを参照してください。実際の例を見ることもお勧めします。

機能コネクタ

概要

proto へのシリアル化/逆シリアル化

メタデータにアクセスする

独自のtfds.features.FeatureConnectorを作成する

独自の`tfds.features.FeatureConnector`を作成する