리포지토리 구조화

데이터셋을 호스팅하고 공유하려면 Hugging Face Hub에서 데이터셋 저장소를 만들고 데이터 파일을 업로드하세요.

이 가이드에서는 데이터셋을 업로드할 때 데이터셋 저장소를 어떻게 구성해야 하는지 보여줍니다. 지원되는 구조와 파일 형식(.txt, .csv, .parquet, .jsonl, .mp3, .jpg, .zip 등)을 가진 데이터셋은 load_dataset()으로 자동으로 로드되며, Hub의 해당 데이터셋 페이지에 데이터셋 뷰어가 표시됩니다.

주요 사용 사례

가장 단순한 데이터셋 구조는 두 개의 파일, train.csv와 test.csv로 구성됩니다(지원되는 모든 파일 형식에서 작동합니다).

리포지토리에는 README.md 파일도 포함되며, 이는 데이터셋 페이지에 표시되는 데이터셋 카드입니다.

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

이 간단한 경우, 두 개의 스플릿을 가진 데이터셋을 얻게 됩니다: train(train.csv의 예제를 포함)와 test(test.csv의 예제를 포함).

YAML에서 스플릿과 서브셋 정의

분할

여러 파일이 있고 각 파일이 어떤 split에 들어갈지 정의하려면, 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 필드는 필수임을 유의하세요.

구성

데이터셋에는 별도로 로드할 수 있는 여러 데이터 하위 집합이 있을 수 있습니다. 이 경우 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 매개변수

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

Filename splits

비전통적인 split이 없다면, split 이름을 데이터 파일의 어디에 두어도 자동으로 추론됩니다. 유일한 규칙은 split 이름이 test-file.csv와 같이 testfile.csv가 아닌, 숫자, 밑줄, 대시, 공백, 마침표와 같은 비단어 문자로 구분되어야 한다는 것입니다.

예를 들어, 다음 파일 이름은 모두 허용됩니다:

• train split: train.csv, my_train_file.csv, train1.csv
• 검증 분할: validation.csv, my_validation_file.csv, validation1.csv
• 테스트 분할: 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 split으로 처리합니다. 데이터셋의 split이 예상대로 로드되지 않는다면 잘못된 패턴 때문일 수 있습니다.

이름 키워드 분리

스플릿을 명명하는 방법은 여러 가지가 있습니다. 검증 스플릿은 “dev”라고 불리기도 하고, 테스트 스플릿은 “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는 여전히 적절한 split을 추론할 수 있습니다.

편의상 데이터 파일을 서로 다른 디렉터리에 배치할 수도 있습니다. 이 경우, split 이름은 디렉터리 이름에서 추론됩니다.

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