Fitur dataset

Features mendefinisikan struktur internal sebuah dataset. Fitur ini digunakan untuk menentukan format serialisasi yang mendasarinya. Namun, hal yang lebih menarik bagi Anda adalah bahwa Features berisi informasi tingkat tinggi tentang segala hal, mulai dari nama dan tipe kolom, hingga ClassLabel. Anda dapat menganggap Features sebagai tulang punggung dari sebuah dataset.

Format Features sederhana: dict[column_name, column_type]. Ini adalah kamus pasangan nama kolom dan tipe kolom. Tipe kolom menyediakan berbagai opsi untuk mendeskripsikan tipe data yang Anda miliki.

Mari kita lihat fitur dari dataset MRPC pada benchmark GLUE:

>>> from datasets import load_dataset
>>> dataset = load_dataset('nyu-mll/glue', 'mrpc', split='train')
>>> dataset.features
{'idx': Value('int32'),
 'label': ClassLabel(names=['not_equivalent', 'equivalent']),
 'sentence1': Value('string'),
 'sentence2': Value('string'),
}

Fitur Value memberi tahu 🤗 Datasets:

• Tipe data idx adalah int32.
• Tipe data sentence1 dan sentence2 adalah string.

🤗 Datasets mendukung banyak tipe data lain seperti bool, float32 dan binary untuk menyebut beberapa saja.

Lihat Value untuk daftar lengkap tipe data yang didukung.

Fitur ClassLabel memberi tahu 🤗 Datasets bahwa kolom label berisi dua kelas. Kelas tersebut diberi label not_equivalent dan equivalent. Label disimpan sebagai bilangan bulat dalam dataset. Saat Anda mengambil label, ClassLabel.int2str() dan ClassLabel.str2int() melakukan konversi dari nilai bilangan bulat ke nama label, dan sebaliknya.

Jika tipe data Anda berisi daftar objek, maka Anda ingin menggunakan fitur List. Ingat dataset SQuAD?

>>> from datasets import load_dataset
>>> dataset = load_dataset('rajpurkar/squad', split='train')
>>> dataset.features
{'id': Value('string'),
 'title': Value('string'),
 'context': Value('string'),
 'question': Value('string'),
 'answers': {'text': List(Value('string')),
  'answer_start': List(Value('int32'))}}

Field answers dibangun menggunakan dict dari fitur karena dan berisi dua subfield, text dan answer_start, yang masing-masing merupakan daftar string dan int32.

Lihat bagian flatten untuk mempelajari cara mengekstrak subfield bersarang sebagai kolom independen.

Jenis fitur array berguna untuk membuat array dengan berbagai ukuran. Anda dapat membuat array dengan dua dimensi menggunakan Array2D, dan bahkan array dengan lima dimensi menggunakan Array5D.

>>> features = Features({'a': Array2D(shape=(1, 3), dtype='int32')})

Tipe array juga memungkinkan dimensi pertama array untuk bersifat dinamis. Hal ini berguna untuk menangani sekuens dengan panjang yang bervariasi, seperti kalimat, tanpa perlu melakukan padding atau pemotongan input ke bentuk yang seragam.

>>> features = Features({'a': Array3D(shape=(None, 5, 2), dtype='int32')})

Fitur audio

Dataset audio memiliki kolom dengan tipe Audio, yang berisi tiga bidang penting:

• array: data audio yang telah didekodekan, direpresentasikan sebagai array satu dimensi.
• path: jalur ke file audio yang diunduh.
• sampling_rate: laju sampling dari data audio.

Saat Anda memuat dataset audio dan memanggil kolom audio, fitur Audio secara otomatis mendekode dan melakukan resampling file audio:

>>> from datasets import load_dataset, Audio

>>> dataset = load_dataset("PolyAI/minds14", "en-US", split="train")
>>> dataset[0]["audio"]
<datasets.features._torchcodec.AudioDecoder object at 0x11642b6a0>

Gunakan indeks baris terlebih dahulu, lalu kolom audio untuk mengakses dataset audio - dataset[0]["audio"] - guna menghindari proses dekoding dan resampling semua file audio dalam dataset. Jika tidak, ini bisa menjadi proses yang lambat dan memakan waktu jika Anda memiliki dataset yang besar.

Dengan decode=False, tipe Audio hanya memberikan Anda path atau bytes dari file audio, tanpa mendekodekannya menjadi objek torchcodec AudioDecoder,

>>> dataset = load_dataset("PolyAI/minds14", "en-US", split="train").cast_column("audio", Audio(decode=False))
>>> dataset[0]
{'audio': {'bytes': None,
  'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav'},
 'english_transcription': 'I would like to set up a joint account with my partner',
 'intent_class': 11,
 'lang_id': 4,
 'path': '/root/.cache/huggingface/datasets/downloads/extracted/f14948e0e84be638dd7943ac36518a4cf3324e8b7aa331c5ab11541518e9368c/en-US~JOINT_ACCOUNT/602ba55abb1e6d0fbce92065.wav',
 'transcription': 'I would like to set up a joint account with my partner'}

Fitur gambar

Dataset gambar memiliki kolom dengan tipe Image, yang memuat objek PIL.Image dari gambar yang disimpan sebagai byte:

Saat Anda memuat dataset gambar dan memanggil kolom gambar, fitur Image secara otomatis mendekode file gambar:

>>> from datasets import load_dataset, Image

>>> dataset = load_dataset("AI-Lab-Makerere/beans", split="train")
>>> dataset[0]["image"]
<PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=500x500 at 0x125506CF8>

Gunakan indeks baris terlebih dahulu, lalu kolom image - dataset[0]["image"] - untuk mengakses dataset gambar, guna menghindari dekoding semua file gambar dalam dataset. Jika tidak, proses ini bisa menjadi lambat dan memakan waktu jika Anda memiliki dataset yang besar.

Dengan decode=False, tipe Image hanya memberikan Anda path atau bytes dari file gambar, tanpa mendekodekannya menjadi PIL.Image,

>>> dataset = load_dataset("AI-Lab-Makerere/beans", split="train").cast_column("image", Image(decode=False))
>>> dataset[0]["image"]
{'bytes': None,
 'path': '/Users/username/.cache/huggingface/datasets/downloads/extracted/772e7c1fba622cff102b85dd74bcce46e8168634df4eaade7bedd3b8d91d3cd7/train/healthy/healthy_train.265.jpg'}

Tergantung pada dataset, Anda mungkin akan mendapatkan path ke gambar yang diunduh secara lokal, atau konten gambar sebagai bytes jika dataset tidak terdiri dari file-file individual.

Anda juga dapat mendefinisikan dataset gambar dari array numpy:

>>> ds = Dataset.from_dict({"i": [np.zeros(shape=(16, 16, 3), dtype=np.uint8)]}, features=Features({"i": Image()}))

Dan dalam kasus ini, array numpy dikodekan menjadi PNG (atau TIFF jika presisi nilai piksel penting).

Untuk array multi-channel seperti RGB atau RGBA, hanya uint8 yang didukung. Jika Anda menggunakan presisi yang lebih besar, Anda akan menerima peringatan dan array akan diturunkan ke uint8. Untuk gambar skala abu-abu, Anda dapat menggunakan presisi integer atau float yang Anda inginkan selama kompatibel dengan Pillow. Peringatan akan ditampilkan jika presisi integer atau float gambar Anda terlalu tinggi, dan dalam kasus ini array akan diturunkan: array int64 diturunkan ke int32, dan array float64 diturunkan ke float32.

Fitur Mesh

Dataset mesh memiliki kolom dengan tipe Mesh, yang memuat file mesh 3D sebagai objek trimesh.

Saat Anda memuat dataset mesh dan memanggil kolom mesh, fitur Mesh secara otomatis mendekode file mesh:

>>> from datasets import load_dataset, Mesh

>>> dataset = load_dataset("VINAY-UMRETHE/My-Mesh-Dataset", split="train")
>>> dataset[0]["mesh"]
<trimesh.Scene(len(geometry)=33)>

Tergantung pada isi file, trimesh dapat mengembalikan objek trimesh.Trimesh atau objek trimesh.Scene.

Gunakan indeks baris terlebih dahulu, lalu kolom mesh untuk mengindeks dataset mesh - dataset[0]["mesh"] - agar tidak perlu mendekode semua file mesh dalam dataset. Jika tidak, proses ini bisa menjadi lambat dan memakan waktu jika Anda memiliki dataset yang besar.

Dengan decode=False, tipe Mesh memberikan Anda path atau bytes dari file mesh tanpa mendekodekannya dengan trimesh:

>>> dataset = load_dataset("VINAY-UMRETHE/My-Mesh-Dataset", split="train").cast_column("mesh", Mesh(decode=False))
>>> dataset[0]["mesh"]
{'bytes': b'...',
 'path': '00001.glb'}

Fitur Mesh mendukung file .glb, .gltf, .ply, dan .stl. Untuk byte yang tertanam, path yang disimpan digunakan untuk menyimpulkan tipe file mesh.

Fitur Json

Datasets didasarkan pada Arrow, yaitu format kolom, sehingga setiap contoh diharapkan memiliki tipe dan sub-tipe yang sama, serta kamus harus memiliki kunci dan tipe nilai yang sama. Memuat dataset akan menghasilkan error jika tipe field tidak cocok, dan mengisi field yang hilang dalam kamus dengan None sehingga semua kamus memiliki kunci dan tipe nilai yang sama.

Untuk menghindari hal ini dan memungkinkan tipe campuran tanpa error, Anda dapat menggunakan on_mixed_types="use_json" atau menentukan features= dengan tipe Json:

>>> ds = Dataset.from_dict({"a": [0, "foo", {"subfield": "bar"}]})
Traceback (most recent call last):
  ...
  File "pyarrow/error.pxi", line 92, in pyarrow.lib.check_status
pyarrow.lib.ArrowInvalid: Could not convert 'foo' with type str: tried to convert to int64

>>> features = Features({"a": Json()})
>>> ds = Dataset.from_dict({"a": [0, "foo", {"subfield": "bar"}]}, features=features)
>>> ds.features
{'a': Json()}
>>> list(ds["a"])
[0, "foo", {"subfield": "bar"}]

Hal ini juga berguna untuk daftar kamus dengan kunci dan nilai yang sembarang, untuk menghindari pengisian bidang yang hilang dengan None:

>>> ds = Dataset.from_dict({"a": [[{"b": 0}, {"c": 0}]]})
>>> ds.features
{'a': List({'b': Value('int64'), 'c': Value('int64')})}
>>> list(ds["a"])
[[{'b': 0, 'c': None}, {'b': None, 'c': 0}]]  # missing fields are filled with None

>>> features = Features({"a": List(Json())})
>>> ds = Dataset.from_dict({"a": [[{"b": 0}, {"c": 0}]]}, features=features)
>>> ds.features
{'a': List(Json())}
>>> list(ds["a"])
[[{'b': 0}, {'c': 0}]]  # OK

Contoh lain dengan data pemanggilan alat dan argumen on_mixed_types="use_json" (berguna agar tidak perlu menentukan features= secara manual):

>>> messages = [
...     {"role": "user", "content": "Turn on the living room lights and play my electronic music playlist."},
...     {"role": "assistant", "tool_calls": [
...         {"type": "function", "function": {
...             "name": "control_light",
...             "arguments": {"room": "living room", "state": "on"}
...         }},
...         {"type": "function", "function": {
...             "name": "play_music",
...             "arguments": {"playlist": "electronic"}  # mixed-type here since keys ["playlist"] and ["room", "state"] are different
...         }}]
...     },
...     {"role": "tool", "name": "control_light", "content": "The lights in the living room are now on."},
...     {"role": "tool", "name": "play_music", "content": "The music is now playing."},
...     {"role": "assistant", "content": "Done!"}
... ]
>>> ds = Dataset.from_dict({"messages": [messages]}, on_mixed_types="use_json")
>>> ds.features
{'messages': List({'role': Value('string'), 'content': Value('string'), 'tool_calls': List(Json()), 'name': Value('string')})}
>>> ds[0][1]["tool_calls"][0]["function"]["arguments"]
{"room": "living room", "state": "on"}