FeatureConnector

API tfds.features.FeatureConnector :

  • Xác định cấu trúc, hình dạng, kiểu của tf.data.Dataset cuối cùng
  • Tóm tắt tuần tự hóa đến / 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 cá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ả dạng 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, 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)
  • Lệnh lồng nhau của các tính năng: {'metadata': {'image': Image(), 'description': tf.string} } dict ...
  • 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 tự động tuần tự hóa bởi FeatureConnector.encode_example 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 được giải mã tự động bằng FeatureConnector.decode_example . tf.data.Dataset trả về sẽ khớp với cấu trúc dict được định nghĩa 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),
    },
}

Serialize / deserialize thành proto

TFDS hiển thị một API cấp thấp để tuần tự hóa / giải mã hóa các ví dụ cho tf.train.Example proto.

Để tuần tự hóa dict[np.ndarray | Path | str | ...] thành bytes proto, 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)

Để deserialize thành bytes proto 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 của các tính năng (tên nhãn, hình dạng, loại, ...). Thí 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 có sẵn , vui lòng mở một vấn đề 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 duy nhất, tốt nhất nên kế thừa từ tfds.features.Tensor và sử dụng super() khi cần. Xem mã nguồn tfds.features.BBoxFeature để làm ví dụ.
  • Nếu tính năng của bạn là một vùng chứa nhiều tensors, 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 kết nối phụ.

Đối tượng tfds.features.FeatureConnector tóm tắt cách mã hóa tính năng trên đĩa từ cách nó được trình bày 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à sự 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 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 dict lệnh của các giá trị.
  • decode_example(data) : Xác định cách giải mã dữ liệu từ tensor được đọc từ tf.train.Example thành tensor của người dùng do tf.data.Dataset trả về.
  • get_tensor_info() : Cho biết hình dạng / kiểu 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 trả về bởi get_tensor_info() 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ố 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 ban đầu. Xem tính năng Âm thanh để làm ví dụ.

Để biết thêm thông tin, hãy xem tài liệu tfds.features.FeatureConnector . Tốt nhất bạn nên xem các ví dụ thực tế .