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アーカイブに格納することもできます。

画像のみ

データセットが画像の1列のみで構成されている場合、画像ファイルをルートに保存するだけです:

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

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を使用できます。

相対パス

メタデータファイルは、リンクされている画像と同じディレクトリ内、またはその親ディレクトリ内のいずれかに配置する必要があります。以下の例を参照してください。

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）の2つのカラムが含まれます。

複数のスプリットを指定することもできます。その場合、データセットのディレクトリは以下の構造になっている必要があります（詳細はファイル名とスプリットを参照してください）：

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アーカイブを作成します。 1つのアーカイブあたりの一般的なサイズは約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ではサポートされていない生バイトなどのデータを保存するためにも役立ちます。

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内で、カラムのフィーチャータイプを直接指定する必要があります。例:

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

Parquet は、小さな画像（1 画像あたり 1MB 未満）および小さな行グループ（1 行グループあたり 100 行。これは datasets が画像に使用している設定です）に適しています。より大きな画像には、WebDataset フォーマットを使用するか、元の画像ファイルを共有すること（必要に応じてメタデータファイルとともに、ストレージおよびファイル数に関するリポジトリの推奨事項と制限に従う）が推奨されます。

Update on GitHub

←オーディオデータセット Video Dataset→