이미지 데이터셋

이미지 데이터셋

이 가이드는 이미지 파일로 데이터셋 리포지토리를 구성하는 방법을 보여줘요. 동반 예시 리포지토리는 이 Image datasets examples 컬렉션에서 찾을 수 있어요.

지원되는 구조와 파일 형식을 가진 데이터셋은 Hub 페이지에 Dataset Viewer가 자동으로 생겨요.

캡션이나 객체 탐지용 바운딩 박스 같은 이미지에 대한 추가 정보는 메타데이터 파일(metadata.csv/metadata.jsonl/metadata.parquet)에 포함하면 자동으로 로드돼요.

또는 이미지를 Parquet 파일이나 WebDataset 형식의 TAR 아카이브에 넣을 수 있어요.

출처: 문서

본문

이미지만 있을 때

데이터셋이 이미지 하나의 컬럼으로만 이루어져 있다면 이미지 파일을 루트에 간단히 저장할 수 있어요:

my_dataset_repository/
├── 1.jpg
├── 2.jpg
├── 3.jpg
└── 4.jpg

또는 하위 디렉터리에:

my_dataset_repository/
└── images
    ├── 1.jpg
    ├── 2.jpg
    ├── 3.jpg
    └── 4.jpg

PNG, JPEG, TIFF, WebP를 포함해 여러 형식을 동시에 지원해요.

my_dataset_repository/
└── images
    ├── 1.jpg
    ├── 2.png
    ├── 3.tiff
    └── 4.webp

여러 스플릿이 있다면 이미지를 그에 맞춘 이름의 디렉터리에 넣을 수 있어요:

my_dataset_repository/
├── train
│   ├── 1.jpg
│   └── 2.jpg
└── test
    ├── 3.jpg
    └── 4.jpg

스플릿별로 데이터를 구성하는 다른 방법과 자세한 내용은 파일 이름과 스플릿을 참고해요.

추가 컬럼

텍스트 캡션이나 바운딩 박스 같은 데이터셋에 대한 추가 정보를 포함하고 싶다면 리포지토리에 metadata.csv 파일로 추가해요. 이렇게 하면 텍스트 캡셔닝이나 객체 탐지 같은 다양한 컴퓨터 비전 작업용 데이터셋을 빠르게 만들 수 있어요.

my_dataset_repository/
└── train
    ├── 1.jpg
    ├── 2.jpg
    ├── 3.jpg
    ├── 4.jpg
    └── metadata.csv

metadata.csv 파일에는 이미지 파일을 그 메타데이터와 연결하는 file_name 컬럼이 있어야 해요:

file_name,text
1.jpg,a drawing of a green pokemon with red eyes
2.jpg,a green and yellow toy with a red nose
3.jpg,a red and white ball with an angry look on its face
4.jpg,a cartoon ball with a smile on its face

JSONL 파일 metadata.jsonl도 사용할 수 있어요:

{"file_name": "1.jpg","text": "a drawing of a green pokemon with red eyes"}
{"file_name": "2.jpg","text": "a green and yellow toy with a red nose"}
{"file_name": "3.jpg","text": "a red and white ball with an angry look on its face"}
{"file_name": "4.jpg","text": "a cartoon ball with a smile on its face"}

더 큰 데이터셋이거나 고급 데이터 검색 기능에 관심이 있다면 Parquet 파일 metadata.parquet를 사용할 수 있어요.

상대 경로

메타데이터 파일은 연결된 이미지와 같은 디렉터리나 임의의 상위 디렉터리에 있어야 해요. 예:

my_dataset_repository/
└── train
    ├── images
    │   ├── 1.jpg
    │   ├── 2.jpg
    │   ├── 3.jpg
    │   └── 4.jpg
    └── metadata.csv

이 경우 file_name 컬럼은 파일명이 아니라 이미지에 대한 전체 상대 경로여야 해요:

file_name,text
images/1.jpg,a drawing of a green pokemon with red eyes
images/2.jpg,a green and yellow toy with a red nose
images/3.jpg,a red and white ball with an angry look on its face
images/4.jpg,a cartoon ball with a smile on it's face

메타데이터 파일은 이미지가 있는 디렉터리의 하위 디렉터리에는 둘 수 없어요.

일반적으로 file_name 또는 *_file_name이라는 이름의 어떤 컬럼이든 이미지에 대한 전체 상대 경로를 담아야 해요.

이미지 분류

이미지 분류 데이터셋은 간단한 설정을 쓸 수도 있어요: 디렉터리를 사용해 이미지 클래스를 이름 지어요. 이미지 파일을 다음과 같은 디렉터리 구조에 저장해요:

my_dataset_repository/
├── green
│   ├── 1.jpg
│   └── 2.jpg
└── red
    ├── 3.jpg
    └── 4.jpg

이 구조로 만든 데이터셋은 image와 label(값은 green, red) 두 컬럼을 가져요.

여러 스플릿도 제공할 수 있어요. 그러려면 데이터셋 디렉터리가 다음 구조를 가져야 해요(자세한 내용은 파일 이름과 스플릿 참고):

my_dataset_repository/
├── test
│   ├── green
│   │   └── 2.jpg
│   └── red
│       └── 4.jpg
└── train
    ├── green
    │   └── 1.jpg
    └── red
        └── 3.jpg

이 자동 label 컬럼 추가는 YAML 구성에서 비활성화할 수 있어요. 디렉터리 이름에 특별한 의미가 없다면 README 헤더에 drop_labels: true를 설정해요:

configs:
  - config_name: default  # Name of the dataset subset, if applicable.
    drop_labels: true

대규모 데이터셋

WebDataset 형식

WebDataset 형식은 대규모 이미지 데이터셋에 잘 맞아요(예: timm/imagenet-12k-wds). 이미지와 메타데이터를 담은 TAR 아카이브로 구성되며 스트리밍에 최적화되어 있어요. 이미지 수가 많고 대규모 학습을 위한 스트리밍 데이터 로더를 원할 때 유용해요.

my_dataset_repository/
├── train-0000.tar
├── train-0001.tar
├── ...
└── train-1023.tar

WebDataset TAR 아카이브를 만들려면 보관할 이미지·메타데이터 파일을 담은 디렉터리를 만들고 예를 들어 tar 명령으로 TAR 아카이브를 만들어요. 아카이브당 일반적인 크기는 보통 1GB 정도예요. 각 이미지와 메타데이터 쌍이 같은 파일 접두어를 공유하는지 확인해요. 예:

train-0000/
├── 000.jpg
├── 000.json
├── 001.jpg
├── 001.json
├── ...
├── 999.jpg
└── 999.json

사용자 편의와 Dataset Viewer 사용을 위해, Hub에 호스팅된 모든 데이터셋은 최대 5GB까지 자동으로 Parquet 형식으로 변환된다는 점을 참고해요. 자세한 내용은 Parquet 형식 문서에서 읽어보세요.

Parquet 형식

이미지와 메타데이터를 개별 파일로 업로드하는 대신 모든 것을 Parquet 파일 안에 넣을 수 있어요. 이미지 수가 많거나, 여러 이미지 컬럼을 넣고 싶거나, 같은 파일에 이미지에 대한 추가 정보를 저장하고 싶을 때 유용해요. Parquet은 JSON/CSV가 지원하지 않는 raw 바이트 같은 데이터를 저장하는 데도 유용해요.

my_dataset_repository/
└── train.parquet

이미지 데이터가 있는 Parquet 파일은 pandas나 datasets 라이브러리로 만들 수 있어요. pandas에서 이미지 데이터로 Parquet 파일을 만들려면 pandas-image-methods와 df.to_parquet()를 사용할 수 있어요. datasets에서는 컬럼 타입을 Image()로 설정하고 ds.to_parquet(...) 메서드나 ds.push_to_hub(...)를 사용할 수 있어요. datasets에서 이미지 데이터셋을 로드하는 가이드는 여기에서 찾을 수 있어요.

또는 다른 도구로 만든 Parquet의 이미지 타입을 수동으로 설정할 수 있어요. 먼저 이미지 컬럼이 이미지 데이터용 이진 필드 "bytes"와 이미지 파일명·경로용 문자열 필드 "path"를 가진 struct 타입인지 확인해요. 그런 다음 README 헤더의 YAML에서 컬럼 특징 타입을 직접 지정해요. 예:

dataset_info:
  features:
  - name: image
    dtype: image
  - name: caption
    dtype: string

Parquet은 작은 이미지(이미지당 <1MB)와 작은 행 그룹(행 그룹당 100행)에 권장돼요. 더 큰 이미지는 WebDataset 형식을 사용하거나 원본 이미지 파일을 공유하는 걸 권장해요(선택적으로 메타데이터 파일과 함께, 스토리지와 파일 수에 대한 리포지토리 권장사항·제한을 따르면서).

더 알아보기 (Learn more)

• 이미지 파일을 루트·하위 디렉터리·스플릿별 디렉터리에 배치하면 Dataset Viewer가 자동 생성돼요.
• 캡션·바운딩 박스는 metadata.csv/metadata.jsonl/metadata.parquet에 file_name으로 연결해요.
• 대규모 데이터셋은 WebDataset TAR 또는 Parquet 형식으로 올려요.