建立影片資料集

本指南將說明如何使用 VideoFolder 搭配一些元數據（metadata）來建立影片資料集。這是一個無需程式碼的解決方案，可讓您快速建立包含數千部影片的資料集。

您可以要求使用者先分享其聯絡資訊，藉此控管對資料集的存取權限。請查看 Gated datasets (受限資料集) 指南，了解如何在 Hub 上啟用此功能。

VideoFolder

VideoFolder 是一個資料集建構器，專為快速載入數千部影片的資料集而設計，無需編寫任何程式碼。

💡 查看分割模式階層 (Split pattern hierarchy) 以深入了解 VideoFolder 如何根據您的資料集儲存庫結構來建立資料集分割。

VideoFolder 會根據目錄名稱自動推斷資料集的類別標籤。請依照下列目錄結構儲存您的資料集：

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

如果資料集遵循 VideoFolder 的結構，您就可以直接使用 load_dataset() 載入它。

>>> from datasets import load_dataset

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

這等同於在 load_dataset() 中手動傳入 videofolder，並在 data_dir 中指定目錄。

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

您也可以使用 videofolder 來載入包含多個分割的資料集。若要執行此操作，您的資料集目錄應具有以下結構：

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

如果所有影片檔案都包含在單一目錄中，或者它們不在同一層級的目錄結構中，則不會自動加入 label 欄位。如果您需要它，請明確設定 drop_labels=False。

如果您想加入有關資料集的額外資訊（例如文字註解或邊界框），請在資料夾中新增一個 metadata.csv 檔案。這讓您可以快速為不同的電腦視覺任務建立資料集，例如文字描述 (captioning) 或物件偵測。您也可以使用 metadata.jsonl (JSONL 檔案) 或 metadata.parquet (Parquet 檔案)。

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

您的 metadata.csv 檔案必須具有 file_name 或 *_file_name 欄位，用以將影片檔案與其元數據連結起來。

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

或者使用 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"}

這裡的 file_name 必須是元數據檔案旁影片檔案的名稱。更通俗地說，它必須是從包含元數據的目錄到影片檔案的相對路徑。

您的資料集中的每一列可以指向一個以上的影片，例如，當您的輸入和輸出皆為影片時。

{"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"}

您也可以定義影片列表。在這種情況下，您需要將該欄位命名為 file_names 或 *_file_names。以下是一個範例：

{"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"}

影片標註 (Video captioning)

影片標註資料集包含描述影片的文字。一個範例 metadata.csv 可能如下所示：

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

使用 VideoFolder 載入資料集，它將為影片標註建立一個 text 欄位。

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

將資料集上傳至 Hub

建立資料集後，您可以使用 huggingface_hub 將其分享至 Hugging Face。請確保您已安裝 huggingface_hub 函式庫，並且已登入您的 Hugging Face 帳號（詳細資訊請參閱使用 Python 上傳教學）。

使用 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

WebDataset 格式基於 TAR 封存檔，適用於大型影片資料集。事實上，您可以將影片分組為 TAR 封存檔（例如每個 TAR 封存檔 1GB 的影片），並擁有數千個 TAR 封存檔。

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

在壓縮檔中，每個範例都由共用相同前綴 (prefix) 的檔案組成。

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

例如，您可以使用 JSON 或文字檔來存放您的影片標籤/標註/特徵。

有關 WebDataset 格式與 Python 函式庫的更多詳細資訊，請查看 WebDataset 文件。

載入您的 WebDataset，它將會為每個檔案後綴建立一個欄位（此處為“mp4”和“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 是一種開放的多模態 Lakehouse 表格格式。Lance 表格不僅可以原生儲存文字和純量值，還可以在表格數據旁邊儲存大型二進位物件（blobs），例如圖像、音訊和影片。

Lance 提供了一個 blob API，可以方便地在 Lance 資料集中儲存和擷取大型 blob。以下範例展示了如何在不載入較重的影片 blob 的情況下，有效率地瀏覽元數據，然後按需獲取相關的影片 blob。

以下是儲存影片的 Lance 表格的代表性視圖（video_blob 欄位使用 Lance 的 blob 編碼）：

+------------------------------------------+-----------------+-----+------------------------------------------+
| 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}       |
+------------------------------------------+-----------------+-----+------------------------------------------+

從原始影片檔案寫入 Lance 資料集

從磁碟上的原始影片檔案加上相關元數據（例如標註和分數）開始，您可以將一個獨立的 Lance 資料集寫入本機 *.lance 目錄（Lance 資料集是磁碟上的一個目錄，通常以 .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",
)

這會將您的元數據和影片位元組一起儲存在 videos.lance/ 中，因此您可以移動/複製單一目錄，而不必保持獨立的 *.mp4 檔案同步。

以下是儲存影片的 Lance 表格的代表性視圖（video_blob 欄位包含原生儲存為 Lance 資料集內 blob 的資料）：

+------------------------------------------+-----------------+-----+------------------------------------------+
| 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}       |
+------------------------------------------+-----------------+-----+------------------------------------------+

您可以將產生的 videos.lance/ 目錄上傳到 Hub（例如使用 huggingface_hub.HfApi.upload_folder）並將其作為資料集儲存庫進行分享，將元數據和影片整合為單一成品。

Lance 資料集可擴展至非常大的規模（TB 以上），因為資料以列式格式儲存在磁碟上。有關儲存和擷取大型 blob 的最佳實踐資訊，請參閱 blob API 指南。

在寫入大型資料集時，通常最好將每個單獨 *.lance 檔案的大小限制在最多幾 GB。只需透過迭代器收集資料，並在寫入資料集時指定 max_bytes_per_file 參數即可。

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,
)

有關使用 Lance 資料集的更多詳細資訊，請參閱 Lance 文件。在 GitHub 上更新

資料集 (Datasets)

建立影片資料集

VideoFolder

影片標註 (Video captioning)

將資料集上傳至 Hub

WebDataset

Lance

從原始影片檔案寫入 Lance 資料集