Tính năngKết nối

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ụng tfds.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)
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 một tính năng bị thiếu trong các tính năng hiện có , vui lòng mở một số phát hành 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ụng super() khi cần. Xem mã nguồn tfds.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ụng super() để 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 .

Các lớp trừu tượng của DatasetBuilder

Để 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ới tf.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ởi tf.data.Dataset .
get_tensor_info() : Cho biết hình dạng/dtype của (các) tensor được trả về bởi tf.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 được get_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ủa tf.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 nên xem xét các ví dụ thực tế .