수동 구성

수동 구성 (Manual Configuration)

이 가이드는 데이터셋 리포지토리에 커스텀 구조를 구성하는 방법을 보여줘요. 예제 데이터셋 컬렉션이 문서의 각 섹션을 보여줍니다.

출처: 문서

본문

이 가이드는 데이터셋 리포지토리에 커스텀 구조를 구성하는 방법을 보여줍니다. 동반 예제 데이터셋 컬렉션이 문서의 각 섹션을 보여줘요.

지원되는 구조와 파일 포맷을 가진 데이터셋은 Hub의 데이터셋 페이지에 자동으로 Dataset Viewer가 생깁니다. YAML로 Viewer가 사용하는 splits, subsets, builder 파라미터를 정의할 수 있어요.

같은 데이터셋에 여러 subsets("configurations"라고도 함)을 정의하는 것도 가능합니다(예: 데이터셋에 여러 독립 파일이 있을 경우).

Splits

파일이 여러 개 있고 어떤 파일이 어떤 split에 들어갈지 정의하고 싶다면 README.md 맨 위에 YAML을 사용할 수 있어요.

예를 들어 이런 리포지토리가 있다고 해봅시다:

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

README.md 맨 위의 YAML 블록에 configs 필드를 추가하면 splits에 대한 subset을 정의할 수 있어요:

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

경로 리스트를 사용해 split당 여러 파일을 선택할 수도 있어요:

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

[!WARNING] subset이 하나뿐이어도 config_name 필드는 필수입니다.

여러 Subsets (Multiple Subsets)

데이터셋에 개별적으로 사용하고 싶은 여러 데이터 하위 집합이 있을 수 있어요. 예를 들어 각 subset은 Hugging Face Hub의 Dataset Viewer에서 각자의 드롭다운을 갖습니다.

이 경우 YAML의 configs 필드 안에 subset 목록을 정의할 수 있어요:

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

Viewer에 표시되는 subset 순서는 기본값이 먼저, 그다음 알파벳순이라는 점을 참고하세요.

[!TIP] default: true로 기본 subset을 설정할 수 있어요.

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

이는 Dataset Viewer가 어떤 subset을 먼저 보여줄지, 데이터 라이브러리가 기본으로 어떤 subset을 불러올지 정할 때 유용합니다.

데이터 디렉터리 (Data Directory)

data_files로 개별 파일을 나열하는 대신 data_dir을 사용해 디렉터리를 가리킬 수 있어요. 그 디렉터리 안의 파일들은 파일 확장자를 기반으로 자동으로 해석됩니다. 데이터가 하위 디렉터리로 구성된 경우 특히 유용합니다.

예를 들어 각 subset의 데이터가 각자 디렉터리에 있으면 data_dir을 간단히 사용할 수 있어요:

my_dataset_repository/
├── README.md
├── main/
│   ├── train.csv
│   └── test.csv
└── extra/
    ├── train.csv
    └── test.csv

---
configs:
- config_name: main
  data_dir: "main"
- config_name: extra
  data_dir: "extra"
---

data_dir이 설정되면 builder는 그 디렉터리를 기준으로 파일을 해석합니다. 디렉터리에 기본 split 네이밍 패턴과 일치하는 파일(예: train.csv, test.csv)이 있으면 명시적인 data_files 없이도 splits가 자동으로 할당됩니다.

더 많은 제어를 위해 data_dir과 data_files를 조합할 수도 있어요:

---
configs:
- config_name: default
  data_dir: "data"
  data_files:
  - split: train
    path: "training_*.csv"
  - split: test
    path: "eval_*.csv"
---

이 경우 data_files의 path 패턴은 data_dir을 기준으로 해석됩니다.

Builder 파라미터 (Builder parameters)

data_files뿐 아니라 다른 builder 특화 파라미터도 YAML로 전달할 수 있어요. 커스텀 코드 없이 데이터를 불러오는 방식을 더 유연하게 해줍니다. 예를 들어 csv 파일을 불러올 때 subset별로 어떤 구분자(separator)를 사용할지 정의할 수 있어요:

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

각 builder가 가진 파라미터는 특정 builder 문서를 참고하세요.

더 알아보기 (Learn more)

README.md 상단 YAML의 configs로 splits·subsets·data_dir·builder 파라미터를 정의하면 Hub가 자동으로 Dataset Viewer를 만들어 줘요. default: true로 기본 subset을 지정하고, glob 패턴과 sep 같은 파라미터를 적절히 조합해 보세요. 예제는 수동 구성 컬렉션에서 확인할 수 있습니다.