Buat dataset video

Panduan ini akan menunjukkan cara membuat dataset video dengan VideoFolder dan beberapa metadata. Ini adalah solusi tanpa kode untuk dengan cepat membuat dataset video dengan beberapa ribu video.

Anda dapat mengontrol akses ke dataset Anda dengan meminta pengguna untuk membagikan informasi kontak mereka terlebih dahulu. Lihat panduan Gated datasets untuk informasi lebih lanjut tentang cara mengaktifkan fitur ini di Hub.

VideoFolder

VideoFolder adalah pembangun dataset yang dirancang untuk memuat dataset video dengan beberapa ribu video dengan cepat tanpa mengharuskan Anda menulis kode apa pun.

💡 Lihat hierarki pola Split untuk mempelajari lebih lanjut tentang bagaimana VideoFolder membuat split dataset berdasarkan struktur repositori dataset Anda.

VideoFolder secara otomatis menyimpulkan label kelas dari dataset Anda berdasarkan nama direktori. Simpan dataset Anda dalam struktur direktori seperti:

folder/train/dog/golden_retriever.mp4
folder/train/dog/german_shepherd.mp4
folder/train/dog/chihuahua.mp4

folder/train/cat/maine_coon.mp4
folder/train/cat/bengal.mp4
folder/train/cat/birman.mp4

Jika dataset mengikuti struktur VideoFolder, maka Anda dapat memuatnya langsung dengan load_dataset():

>>> from datasets import load_dataset

>>> dataset = load_dataset("path/to/folder")

Ini setara dengan meneruskan videofolder secara manual di load_dataset() dan direktori di data_dir:

>>> dataset = load_dataset("videofolder", data_dir="/path/to/folder")

Anda juga dapat menggunakan videofolder untuk memuat dataset yang melibatkan beberapa split. Untuk melakukannya, direktori dataset Anda harus memiliki struktur berikut:

folder/train/dog/golden_retriever.mp4
folder/train/cat/maine_coon.mp4
folder/test/dog/german_shepherd.mp4
folder/test/cat/bengal.mp4

Jika semua file video berada dalam satu direktori atau tidak berada pada level struktur direktori yang sama, kolom label tidak akan ditambahkan secara otomatis. Jika Anda membutuhkannya, tetapkan drop_labels=False secara eksplisit.

Jika ada informasi tambahan yang ingin Anda sertakan tentang dataset Anda, seperti teks caption atau bounding box, tambahkan sebagai file metadata.csv di folder Anda. Hal ini memungkinkan Anda dengan cepat membuat dataset untuk berbagai tugas computer vision seperti text captioning atau object detection. Anda juga dapat menggunakan file JSONL metadata.jsonl atau file Parquet metadata.parquet.

folder/train/metadata.csv
folder/train/0001.mp4
folder/train/0002.mp4
folder/train/0003.mp4

File metadata.csv Anda harus memiliki field file_name atau *_file_name yang menghubungkan file video dengan metadata mereka:

file_name,additional_feature
0001.mp4,This is a first value of a text feature you added to your videos
0002.mp4,This is a second value of a text feature you added to your videos
0003.mp4,This is a third value of a text feature you added to your videos

atau menggunakan metadata.jsonl:

{"file_name": "0001.mp4", "additional_feature": "This is a first value of a text feature you added to your videos"}
{"file_name": "0002.mp4", "additional_feature": "This is a second value of a text feature you added to your videos"}
{"file_name": "0003.mp4", "additional_feature": "This is a third value of a text feature you added to your videos"}

Di sini, file_name harus berupa nama file video yang berada di samping file metadata. Secara lebih umum, ini harus berupa path relatif dari direktori yang berisi metadata ke file video.

Anda dapat menunjuk ke lebih dari satu video di setiap baris dalam dataset Anda, misalnya jika input dan output Anda sama-sama berupa video:

{"input_file_name": "0001.mp4", "output_file_name": "0001_output.mp4"}
{"input_file_name": "0002.mp4", "output_file_name": "0002_output.mp4"}
{"input_file_name": "0003.mp4", "output_file_name": "0003_output.mp4"}

Anda juga dapat mendefinisikan daftar video. Dalam hal itu, Anda perlu menamai field file_names atau *_file_names. Berikut adalah contohnya:

{"videos_file_names": ["0001_left.mp4", "0001_right.mp4"], "label": "moving_up"}
{"videos_file_names": ["0002_left.mp4", "0002_right.mp4"], "label": "moving_down"}
{"videos_file_names": ["0003_left.mp4", "0003_right.mp4"], "label": "moving_right"}

Captioning video

Dataset captioning video memiliki teks yang mendeskripsikan sebuah video. Contoh metadata.csv mungkin terlihat seperti:

file_name,text
0001.mp4,This is a golden retriever playing with a ball
0002.mp4,A german shepherd
0003.mp4,One chihuahua

Muat dataset dengan VideoFolder, dan kolom text untuk caption video akan dibuat:

>>> dataset = load_dataset("videofolder", data_dir="/path/to/folder", split="train")
>>> dataset[0]["text"]
"This is a golden retriever playing with a ball"

Unggah dataset ke Hub

Setelah Anda membuat dataset, Anda dapat membagikannya menggunakan huggingface_hub, misalnya. Pastikan Anda telah menginstal pustaka huggingface_hub dan telah masuk ke akun Hugging Face Anda (lihat tutorial Upload with Python untuk detail lebih lanjut).

Unggah dataset Anda dengan huggingface_hub.HfApi.upload_folder:

from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path="/path/to/local/dataset",
    repo_id="username/my-cool-dataset",
    repo_type="dataset",
)

WebDataset

Format WebDataset didasarkan pada arsip TAR dan cocok untuk dataset video besar. Anda dapat mengelompokkan video Anda ke dalam arsip TAR (misalnya 1GB video per arsip TAR) dan memiliki ribuan arsip TAR:

folder/train/00000.tar
folder/train/00001.tar
folder/train/00002.tar
...

Di arsip, setiap contoh terdiri dari file-file yang berbagi prefiks yang sama:

e39871fd9fd74f55.mp4
e39871fd9fd74f55.json
f18b91585c4d3f3e.mp4
f18b91585c4d3f3e.json
ede6e66b2fb59aab.mp4
ede6e66b2fb59aab.json
ed600d57fcee4f94.mp4
ed600d57fcee4f94.json
...

Anda dapat menempatkan label/keterangan/fitur video Anda menggunakan file JSON atau teks, misalnya.

Untuk detail lebih lanjut tentang format WebDataset dan pustaka python, silakan periksa dokumentasi WebDataset.

Muat WebDataset Anda dan akan dibuat satu kolom per akhiran file (di sini “mp4” dan “json”):

>>> from datasets import load_dataset

>>> dataset = load_dataset("webdataset", data_dir="/path/to/folder", split="train")
>>> dataset[0]["json"]
{"bbox": [[302.0, 109.0, 73.0, 52.0]], "categories": [0]}

Lance

Lance adalah format tabel lakehouse multimodal terbuka. Tabel Lance dapat menyimpan secara native tidak hanya teks dan nilai skalar, tetapi juga objek biner besar (blobs) seperti gambar, audio, dan video berdampingan dengan data tabular Anda.

Lance menyediakan blob API yang memudahkan penyimpanan dan pengambilan blob besar dalam dataset Lance. Contoh berikut menunjukkan cara menelusuri metadata secara efisien tanpa memuat blob video yang lebih berat, lalu mengambil blob video yang relevan sesuai kebutuhan.

Berikut adalah tampilan representatif dari tabel Lance yang menyimpan video (kolom video_blob menggunakan enkripsi blob Lance):

+------------------------------------------+-----------------+-----+------------------------------------------+
| caption                                  | aesthetic_score | ... | video_blob                               |
+------------------------------------------+-----------------+-----+------------------------------------------+
| "a breathtaking view of a mounta..."     | 5.2401          | ... | {position: 0, size: 4873879}             |
| "a captivating view of the sun, b..."    | 5.2401          | ... | {position: 4873920, size: 3370571}       |
+------------------------------------------+-----------------+-----+------------------------------------------+

Menulis dataset Lance dari file video mentah

Berangkat dari file video mentah di disk beserta metadata terkait (misalnya, caption dan skor), Anda dapat menulis dataset Lance yang mandiri ke direktori *.lance lokal (dataset Lance adalah direktori di disk, dan umum untuk menamainya dengan akhiran .lance):

import lance
import pyarrow as pa

import urllib.request

schema = pa.schema(
    [
        pa.field("caption", pa.utf8()),
        pa.field("aesthetic_score", pa.float64()),
        pa.field(
            "video_blob",
            pa.large_binary(),
            metadata={"lance-encoding:blob": "true"},
        ),
    ]
)

# Provide video files alongside metadata
rows = [
    {
        "video_path": "/path/to/videos/0001.mp4",
        "caption": "a breathtaking view of a mountainous landscape ...",
        "aesthetic_score": 5.240138053894043,
    },
    {
        "video_path": "0002.mp4",
        "caption": "a captivating view of the sun, bathed in hues ...",
        "aesthetic_score": 5.240137100219727,
    },
]

video_bytes = []
for r in rows:
    with open(r["video_path"], "rb") as f:
        video_bytes.append(f.read())

table = pa.table(
    {
        "caption": [r["caption"] for r in rows],
        "aesthetic_score": [r["aesthetic_score"] for r in rows],
        "video_blob": video_bytes,
    },
    schema=schema,
)

ds = lance.write_dataset(
    table,
    "./videos.lance",
    schema=schema,
    mode="create",
)

Ini menyimpan metadata dan byte video Anda bersama di dalam videos.lance/, sehingga Anda dapat memindahkan/menyalin satu direktori tanpa harus menjaga sinkronisasi file *.mp4 terpisah.

Berikut adalah tampilan representatif dari tabel Lance yang menyimpan video (kolom video_blob berisi data yang disimpan secara native sebagai blob di dalam dataset Lance):

+------------------------------------------+-----------------+-----+------------------------------------------+
| caption                                  | aesthetic_score | ... | video_blob                               |
+------------------------------------------+-----------------+-----+------------------------------------------+
| "a breathtaking view of a mounta..."     | 5.2401          | ... | {position: 0, size: 4873879}             |
| "a captivating view of the sun, b..."    | 5.2401          | ... | {position: 4873920, size: 3370571}       |
+------------------------------------------+-----------------+-----+------------------------------------------+

Anda dapat mengunggah direktori videos.lance/ yang dihasilkan ke Hub (misalnya dengan huggingface_hub.HfApi.upload_folder) dan membagikannya sebagai repositori dataset, sehingga metadata dan video tetap bersama sebagai satu artefak.

Dataset Lance dapat diskalakan ke ukuran yang sangat besar (terabyte dan lebih) karena data disimpan dalam format kolom di disk. Lihat panduan API blob untuk informasi terbaru tentang praktik terbaik dalam menyimpan dan mengambil blob besar di Lance.

Saat menulis dataset besar, biasanya sebaiknya membatasi ukuran setiap file *.lance individual menjadi beberapa gigabyte saja. Cukup kumpulkan data melalui iterator dan tentukan parameter max_bytes_per_file saat menulis dataset:

MAX_BYTES_PER_FILE = 5 * 1024 * 1024 * 1024  # ~5 GB per file

# Write as Lance dataset with file size limits for each *.lance file
ds = lance.write_dataset(
    table,
    "./videos.lance",
    schema=schema,
    mode="create",
    max_bytes_per_file=MAX_BYTES_PER_FILE,
)

Untuk detail lebih lanjut tentang cara bekerja dengan dataset Lance, lihat dokumentasi Lance.