API tfds.features.FeatureConnector
:
- Xác định cấu trúc, hình dạng, kiểu dữ liệu của
tf.data.Dataset
cuối cùng - Tóm tắt việc tuần tự hóa vào/từ đĩa.
- Hiển thị siêu dữ liệu bổ sung (ví dụ: tên nhãn, tốc độ mẫu âm thanh, ...)
Tổng quan
tfds.features.FeatureConnector
xác định cấu trúc tính năng của tập dữ liệu (trong 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,
},
}),
)
Các tính năng có thể được ghi lại bằng cách chỉ sử dụng mô tả văn bản ( doc='description'
) hoặc bằng cách sử dụng trực tiếp tfds.features.Documentation
để cung cấp mô tả tính năng chi tiết hơn.
Các tính năng có thể là:
- Giá trị vô hướng:
tf.bool
,tf.string
,tf.float32
,... Khi bạn muốn ghi lại đối tượng địa lý, bạn cũng có thể sử dụngtfds.features.Scalar(tf.int64, doc='description')
. -
tfds.features.Audio
,tfds.features.Video
,... (xem danh sách các tính năng có sẵn) - Chính
dict
lồng nhau của các tính năng:{'metadata': {'image': Image(), 'description': tf.string} }
,... - Lồng nhau
tfds.features.Sequence
:Sequence({'image': ..., 'id': ...})
,Sequence(Sequence(tf.int64))
,...
Trong quá trình tạo, các ví dụ sẽ được FeatureConnector.encode_example
tự động tuần tự hóa thành định dạng phù hợp với đĩa (hiện tại là bộ đệm giao thức 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',
},
}
Khi đọc tập dữ liệu (ví dụ: với tfds.load
), dữ liệu sẽ được giải mã tự động bằng FeatureConnector.decode_example
. tf.data.Dataset
được trả về sẽ khớp với cấu trúc dict
được xác định trong tfds.core.DatasetInfo
:
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),
},
}
Tuần tự hóa/giải tuần tự hóa thành proto
TFDS hiển thị API cấp thấp để tuần tự hóa/giải tuần tự hóa các ví dụ thành tf.train.Example
proto.
Để tuần tự hóa dict[np.ndarray | Path | str | ...]
thành bytes
proto, hãy sử dụng 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)
Để giải tuần tự hóa bytes
nguyên mẫu thành tf.Tensor
, hãy sử dụng features.deserialize_example
:
ds = tf.data.TFRecordDataset('path/to/file.tfrecord')
ds = ds.map(features.deserialize_example)
Truy cập siêu dữ liệu
Xem tài liệu giới thiệu để truy cập siêu dữ liệu về tính năng (tên nhãn, hình dạng, dtype,...). Ví dụ:
ds, info = tfds.load(..., with_info=True)
info.features['label'].names # ['cat', 'dog', ...]
info.features['label'].str2int('cat') # 0
Tạo tfds.features.FeatureConnector
của riêng bạn
Nếu bạn cho rằng tính năng sẵn có bị thiếu, vui lòng mở một số mới .
Để tạo trình kết nối tính năng của riêng bạn, bạn cần kế thừa từ tfds.features.FeatureConnector
và triển khai các phương thức trừu tượng.
- Nếu tính năng của bạn là một giá trị tensor đơn, thì tốt nhất bạn nên kế thừa từ
tfds.features.Tensor
và sử dụngsuper()
khi cần. Xem mã nguồntfds.features.BBoxFeature
để biết ví dụ. - Nếu đối tượng địa lý của bạn là vùng chứa nhiều tensor, tốt nhất nên kế thừa từ
tfds.features.FeaturesDict
và sử dụngsuper()
để tự động mã hóa các đầu nối phụ.
Đối tượng tfds.features.FeatureConnector
tóm tắt cách tính năng được mã hóa trên đĩa từ cách nó được hiển thị cho người dùng. Dưới đây là sơ đồ hiển thị các lớp trừu tượng của tập dữ liệu và quá trình chuyển đổi từ các tệp tập dữ liệu thô sang đối tượng tf.data.Dataset
.
Để tạo trình kết nối tính năng của riêng bạn, hãy phân lớp tfds.features.FeatureConnector
và triển khai các phương thức trừu tượng:
-
encode_example(data)
: Xác định cách mã hóa dữ liệu được cung cấp trong trình tạo_generate_examples()
thành dữ liệu tương thích vớitf.train.Example
. Có thể trả về một giá trị duy nhất hoặc một giá trịdict
. -
decode_example(data)
: Xác định cách giải mã dữ liệu từ tensor được đọc từtf.train.Example
sang tensor người dùng được trả về bởitf.data.Dataset
. -
get_tensor_info()
: Cho biết hình dạng/dtype của (các) tensor được trả về bởitf.data.Dataset
. Có thể là tùy chọn nếu kế thừa từtfds.features
khác. - (tùy chọn)
get_serialized_info()
: Nếu thông tin đượcget_tensor_info()
trả về khác với cách dữ liệu thực sự được ghi trên đĩa thì bạn cần ghi đèget_serialized_info()
để khớp với thông số kỹ thuật củatf.train.Example
-
to_json_content
/from_json_content
: Điều này là bắt buộc để cho phép tải tập dữ liệu của bạn mà không cần mã nguồn gốc. Xem tính năng Âm thanh để biết ví dụ.
Để biết thêm thông tin, hãy xem tài liệu tfds.features.FeatureConnector
. Tốt nhất là hãy nhìn vào những ví dụ thực tế .