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 を公開します。
dict[np.ndarray | Path | str | ...]をシリアル化するにはdict[np.ndarray | Path | str | ...] proto bytesに変換するには、 features.serialize_exampleを使用します。
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オブジェクトへの変換を示す図です。
独自の機能コネクタを作成するには、 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のドキュメントを参照してください。実際の例を見ることもお勧めします。