建構您的儲存庫

若要託管並分享您的資料集，請在 Hugging Face Hub 上建立一個資料集儲存庫並上傳您的資料檔案。

本指南將說明在上傳時如何建構您的資料集儲存庫。具有支援結構與檔案格式（.txt、.csv、.parquet、.jsonl、.mp3、.jpg、.zip 等）的資料集可透過 load_dataset() 自動載入，並會在 Hub 的資料集頁面上顯示資料集檢視器。

主要使用案例

最簡單的資料集結構包含兩個檔案：train.csv 和 test.csv（這適用於任何支援的檔案格式）。

您的儲存庫還應包含一個 README.md 檔案，即顯示在資料集頁面上的資料集卡片 (dataset card)。

my_dataset_repository/
├── README.md
├── train.csv
└── test.csv

在這個簡單的案例中，您將獲得一個包含兩個分割 (splits) 的資料集：train（包含來自 train.csv 的範例）和 test（包含來自 test.csv 的範例）。

在 YAML 中定義您的分割與子集

分割集

如果您有多個檔案並希望定義哪個檔案屬於哪個分割，您可以使用 README.md 頂部的 YAML configs 欄位。

例如，假設有一個像這樣的儲存庫

my_dataset_repository/
├── README.md
├── data.csv
└── holdout.csv

您可以透過在 README.md 頂部的 YAML 區塊中加入 configs 欄位來定義您的分割

---
configs:
- config_name: default
  data_files:
  - split: train
    path: "data.csv"
  - split: test
    path: "holdout.csv"
---

您可以使用路徑列表為每個分割選擇多個檔案

my_dataset_repository/
├── README.md
├── data/
│   ├── abc.csv
│   └── def.csv
└── holdout/
    └── ghi.csv

---
configs:
- config_name: default
  data_files:
  - split: train
    path:
    - "data/abc.csv"
    - "data/def.csv"
  - split: test
    path: "holdout/ghi.csv"
---

或者您可以使用 Glob 模式來自動列出所有您需要的檔案

---
configs:
- config_name: default
  data_files:
  - split: train
    path: "data/*.csv"
  - split: test
    path: "holdout/*.csv"
---

請注意，即使您只有一個配置，config_name 欄位也是必需的。

配置 (Configurations)

您的資料集可能有多個想要分別載入的資料子集。在這種情況下，您可以在 YAML 的 configs 欄位內定義一個配置列表

my_dataset_repository/
├── README.md
├── main_data.csv
└── additional_data.csv

---
configs:
- config_name: main_data
  data_files: "main_data.csv"
- config_name: additional_data
  data_files: "additional_data.csv"
---

每個配置都會在 Hugging Face Hub 上分別顯示，並可透過將其名稱作為第二個參數傳入來載入

from datasets import load_dataset

main_data = load_dataset("my_dataset_repository", "main_data")
additional_data = load_dataset("my_dataset_repository", "additional_data")

建構器參數 (Builder parameters)

不僅是 data_files，其他建構器特定的參數也可以透過 YAML 傳遞，這讓載入資料的方式更具靈活性，且無需任何自訂程式碼。例如，定義在載入 csv 檔案時要在哪個配置中使用哪個分隔符

---
configs:
- config_name: tab
  data_files: "main_data.csv"
  sep: "\t"
- config_name: comma
  data_files: "additional_data.csv"
  sep: ","
---

請參閱特定建構器的文件以了解它們擁有的配置參數。

您可以透過 default: true 設定預設配置，例如，如果您設定了以下內容，就可以執行 main_data = load_dataset("my_dataset_repository")
- config_name: main_data
  data_files: "main_data.csv"
  default: true

自動分割偵測

如果未提供 YAML，🤗 Datasets 會在資料集儲存庫中搜尋特定模式以自動推斷資料集分割。這些模式有一定的順序，從自訂檔案名稱分割格式開始，如果找不到任何模式，則將所有檔案視為單一分割。

目錄名稱

您的資料檔案也可以放置在名為 train、test 和 validation 的不同目錄中，每個目錄包含該分割的資料檔案。

my_dataset_repository/
├── README.md
└── data/
    ├── train/
    │   └── bees.csv
    ├── test/
    │   └── more_bees.csv
    └── validation/
        └── even_more_bees.csv

檔案名稱分割

如果您沒有任何非傳統的分割，那麼您可以將分割名稱放置在資料檔案中的任何位置，它會被自動推斷。唯一的規則是分割名稱必須由非文字字元分隔，例如使用 test-file.csv 而不是 testfile.csv。支援的分隔符包括底線、連字號、空格、點和數字。

例如，以下檔案名稱皆為可接受的：

train 分割：train.csv、my_train_file.csv、train1.csv
validation 分割：validation.csv、my_validation_file.csv、validation1.csv
test 分割：test.csv、my_test_file.csv、test1.csv

這是一個將所有檔案放置在名為 data 目錄中的範例

my_dataset_repository/
├── README.md
└── data/
    ├── train.csv
    ├── test.csv
    └── validation.csv

自訂檔案名稱分割

如果您的資料集分割具有非 train、test 或 validation 的自訂名稱，那麼您可以將資料檔案命名為 data/<split_name>-xxxxx-of-xxxxx.csv。

這是一個包含三個分割的範例：train、test 和 random

my_dataset_repository/
├── README.md
└── data/
    ├── train-00000-of-00003.csv
    ├── train-00001-of-00003.csv
    ├── train-00002-of-00003.csv
    ├── test-00000-of-00001.csv
    ├── random-00000-of-00003.csv
    ├── random-00001-of-00003.csv
    └── random-00002-of-00003.csv

單一分割

當 🤗 Datasets 找不到上述任何模式時，它會將所有檔案視為單一的 train 分割。如果您的資料集分割未按預期載入，可能是因為模式不正確。

分割名稱關鍵字

命名分割的方式有多種。Validation 分割有時稱為“dev”，而 test 分割可能稱為“eval”。這些其他分割名稱也受支援，以下關鍵字是等效的：

train, training
validation, valid, val, dev
test, testing, eval, evaluation

下方的結構是一個有效的儲存庫

my_dataset_repository/
├── README.md
└── data/
    ├── training.csv
    ├── eval.csv
    └── valid.csv

每個分割多個檔案

如果您的其中一個分割包含多個檔案，🤗 Datasets 仍然可以從檔案名稱推斷它是 train、validation 還是 test 分割。例如，如果您的 train 和 test 分割跨越了多個檔案

my_dataset_repository/
├── README.md
├── train_0.csv
├── train_1.csv
├── train_2.csv
├── train_3.csv
├── test_0.csv
└── test_1.csv

請確保您的 train 集合的所有檔案名稱中都有 train（測試集和驗證集同理）。即使您在檔案名稱中加入了 train 的前綴或後綴（例如 my_train_file_00001.csv），🤗 Datasets 仍然可以推斷出適當的分割。

為了方便起見，您也可以將資料檔案放置到不同的目錄中。在這種情況下，分割名稱會從目錄名稱中推斷出來。

my_dataset_repository/
├── README.md
└── data/
    ├── train/
    │   ├── shard_0.csv
    │   ├── shard_1.csv
    │   ├── shard_2.csv
    │   └── shard_3.csv
    └── test/
        ├── shard_0.csv
        └── shard_1.csv

在 GitHub 上更新