Cấu trúc kho lưu trữ của bạn

Để lưu trữ và chia sẻ bộ dữ liệu của bạn, hãy tạo một kho dữ liệu trên Hugging Face Hub và tải lên các tệp dữ liệu của bạn.

Hướng dẫn này sẽ cho bạn thấy cách tổ chức kho dữ liệu của mình khi tải lên. Một bộ dữ liệu có cấu trúc và định dạng tệp được hỗ trợ (.txt, .csv, .parquet, .jsonl, .mp3, .jpg, .zip v.v.) sẽ được tải tự động bằng load_dataset(), và sẽ có trình xem dữ liệu trên trang dữ liệu của nó trên Hub.

Trường hợp sử dụng chính

Cấu trúc tập dữ liệu đơn giản nhất gồm hai tệp: train.csv và test.csv (cách này hoạt động với bất kỳ định dạng tệp nào được hỗ trợ).

Kho lưu trữ của bạn cũng sẽ chứa tệp README.md, tức là thẻ dữ liệu được hiển thị trên trang dữ liệu của bạn.

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

Trong trường hợp đơn giản này, bạn sẽ nhận được một dataset với hai splits: train (chứa các ví dụ từ train.csv) và test (chứa các ví dụ từ test.csv).

Định nghĩa các phần chia và tập con của bạn trong YAML

Các phần chia

Nếu bạn có nhiều tệp và muốn xác định tệp nào thuộc phần chia (split) nào, bạn có thể sử dụng trường configs dạng YAML ở đầu tệp README.md.

Ví dụ, với một kho lưu trữ như sau:

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

Bạn có thể định nghĩa các phần chia của mình bằng cách thêm trường configs vào khối YAML ở đầu tệp README.md:

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

Bạn có thể chọn nhiều tệp cho mỗi split bằng cách sử dụng một danh sách các đường dẫn:

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

Hoặc bạn có thể sử dụng các mẫu glob để tự động liệt kê tất cả các tệp cần thiết:

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

Lưu ý rằng trường config_name là bắt buộc ngay cả khi bạn chỉ có một cấu hình.

Cấu hình

Bộ dữ liệu của bạn có thể có một vài tập con dữ liệu mà bạn muốn có thể tải riêng biệt. Trong trường hợp đó, bạn có thể định nghĩa một danh sách các cấu hình bên trong trường configs trong YAML:

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

Mỗi cấu hình được hiển thị riêng biệt trên Hugging Face Hub và có thể được nạp bằng cách truyền tên của nó làm tham số thứ hai:

from datasets import load_dataset

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

Tham số Builder

Không chỉ data_files, mà các tham số cụ thể của builder khác cũng có thể được truyền qua YAML, cho phép linh hoạt hơn trong cách tải dữ liệu mà không cần bất kỳ mã tùy chỉnh nào. Ví dụ, định nghĩa bộ phân tách nào sẽ được sử dụng trong cấu hình nào để tải các tệp csv của bạn:

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

Tham khảo tài liệu của các builder cụ thể để xem chúng có những tham số cấu hình nào.

Bạn có thể đặt cấu hình mặc định bằng cách sử dụng default: true, ví dụ bạn có thể chạy main_data = load_dataset("my_dataset_repository") nếu bạn đặt

Đã sao chép

- config_name: main_data
  data_files: "main_data.csv"
  default: true

Tự động phát hiện các phần chia

Nếu không có YAML được cung cấp, 🤗 Datasets sẽ tìm kiếm các mẫu nhất định trong kho dữ liệu để tự động suy luận các phần chia của bộ dữ liệu. Các mẫu này có thứ tự, bắt đầu từ định dạng phần chia theo tên tệp tùy chỉnh cho đến việc coi tất cả các tệp là một phần chia duy nhất nếu không tìm thấy mẫu nào.

Tên thư mục

Các tệp dữ liệu của bạn cũng có thể được đặt vào các thư mục khác nhau có tên là train, test và validation, trong đó mỗi thư mục chứa các tệp dữ liệu cho phần chia tương ứng:

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

Tách theo tên tệp

Nếu bạn không có bất kỳ phần chia nào phi truyền thống, bạn có thể đặt tên phần chia ở bất kỳ vị trí nào trong tệp dữ liệu và nó sẽ được suy luận tự động. Quy tắc duy nhất là tên phần chia phải được phân tách bằng các ký tự không phải chữ, chẳng hạn như test-file.csv thay vì testfile.csv. Các ký tự phân tách được hỗ trợ bao gồm dấu gạch dưới, dấu gạch nối, khoảng trắng, dấu chấm và chữ số.

Ví dụ, các tên tệp sau đều được chấp nhận:

• tập huấn luyện: train.csv, my_train_file.csv, train1.csv
• tập kiểm định: validation.csv, my_validation_file.csv, validation1.csv
• tập kiểm tra: test.csv, my_test_file.csv, test1.csv

Dưới đây là một ví dụ trong đó tất cả các tệp được đặt vào một thư mục có tên là data:

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

Tách tệp theo tên tệp tùy chỉnh

Nếu các phần chia của bộ dữ liệu của bạn có tên tùy chỉnh không phải là train, test hoặc validation, thì bạn có thể đặt tên cho các tệp dữ liệu của mình như data/<split_name>-xxxxx-of-xxxxx.csv.

Dưới đây là một ví dụ với ba phần chia, train, test và 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

Một lần tách

Khi 🤗 Datasets không tìm thấy bất kỳ mẫu nào ở trên, nó sẽ coi tất cả các tệp là một split train duy nhất. Nếu các split của bộ dữ liệu của bạn không được nạp như mong đợi, nguyên nhân có thể do mẫu không chính xác.

Từ khóa tên tách

Có một số cách để đặt tên cho các phần chia (splits). Phần chia kiểm định (validation) đôi khi được gọi là “dev”, và phần chia kiểm tra (test) có thể được gọi là “eval”. Các tên phần chia khác này cũng được hỗ trợ, và các từ khóa sau đây là tương đương:

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

Cấu trúc bên dưới là một kho lưu trữ hợp lệ:

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

Nhiều tệp cho mỗi phần

Nếu một trong các tập dữ liệu của bạn bao gồm nhiều tệp, 🤗 Datasets vẫn có thể suy luận xem đó là tập huấn luyện, tập xác thực hay tập kiểm tra từ tên tệp. Ví dụ, nếu tập huấn luyện và tập kiểm tra của bạn trải dài trên nhiều tệp:

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

Hãy đảm bảo tất cả các tệp trong tập train của bạn có train trong tên tệp (tương tự cho test và validation). Ngay cả khi bạn thêm tiền tố hoặc hậu tố cho train trong tên tệp (ví dụ như my_train_file_00001.csv), 🤗 Datasets vẫn có thể suy luận được split phù hợp.

Để tiện lợi, bạn cũng có thể đặt các tệp dữ liệu của mình vào các thư mục khác nhau. Trong trường hợp này, tên tập chia (split) sẽ được suy ra từ tên thư mục.

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