Hub documentation

이미지 데이터셋

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

이미지 데이터셋

이 가이드에서는 이미지 파일로 데이터셋 저장소를 구성하는 방법을 보여줍니다. 이 Image datasets examples collection에서 관련 저장소 예시를 찾을 수 있습니다.

지원되는 구조와 파일 형식을 가진 데이터셋은 Hub의 해당 페이지에 Dataset Viewer가 자동으로 표시됩니다.

이미지에 대한 추가 정보(예: 캡션 또는 객체 감지를 위한 바운딩 박스)는 메타데이터 파일(metadata.csv/metadata.jsonl/metadata.parquet)에 이 정보를 포함하는 한 자동으로 로드됩니다.

대신, 이미지는 WebDataset 형식을 따르는 Parquet 파일 또는 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

여러 개의 split이 있는 경우, 각 split에 해당하는 이름의 디렉토리에 이미지를 넣을 수 있습니다:

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

metadata.jsonl라는 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을 사용할 수 있습니다.

상대 경로

Metadata 파일은 연결된 이미지와 동일한 디렉터리에 있거나, 이 예시와 같이 상위 디렉터리에 있어야 합니다:

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

Metadata 파일은 이미지가 포함된 디렉토리의 하위 디렉토리에 배치할 수 없습니다.

더 일반적으로, file_name 또는 *_file_name로 이름이 지정된 모든 열에는 이미지에 대한 전체 상대 경로가 포함되어야 합니다.

이미지 분류

이미지 분류 데이터셋의 경우, 간단한 설정도 사용할 수 있습니다. 디렉토리를 사용하여 이미지 클래스를 이름으로 지정합니다. 이미지 파일을 다음과 같은 디렉토리 구조에 저장하세요:

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

이 구조로 생성된 데이터셋에는 image와 label 두 개의 열이 포함됩니다(값은 green와 red).

여러 개의 split을 제공할 수도 있습니다. 이렇게 하려면 데이터셋 디렉토리가 다음 구조를 가져야 합니다(자세한 내용은 파일 이름과 split을 참고하세요):

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 format 문서를 참고하세요.

Parquet 형식

이미지와 메타데이터를 개별 파일로 업로드하는 대신, 모든 것을 Parquet 파일 안에 포함할 수 있습니다. 이미지의 수가 많거나, 여러 이미지 컬럼을 포함하거나, 이미지와 관련된 추가 정보를 동일한 파일에 저장하려는 경우 유용합니다. Parquet는 JSON/CSV에서 지원하지 않는 원시 바이트(raw bytes)와 같은 데이터를 저장하는 데에도 유용합니다.

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의 이미지 유형을 수동으로 설정할 수도 있습니다. 먼저, 이미지 컬럼의 유형이 struct인지, 이미지 데이터를 위한 바이너리 필드 "bytes"와 이미지 파일 이름 또는 경로를 위한 문자열 필드 "path"가 있는지 확인하세요. 그런 다음 README 헤더의 YAML에서 컬럼의 feature 유형을 직접 지정해야 합니다. 예를 들어:

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

Parquet은 작은 이미지(이미지당 1MB 미만)와 작은 row group(row group당 100행, datasets가 이미지에 사용하는 설정)에 권장됩니다. 더 큰 이미지의 경우 WebDataset 포맷을 사용하거나, 원본 이미지 파일을 공유하는 것(선택적으로 메타데이터 파일과 함께, 저장소 및 파일 수에 대한 저장소 권장 사항 및 제한을 따르며)을 권장합니다.

Update on GitHub

←오디오 데이터셋 비디오 데이터셋→