Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

图像数据集

本指南将向您展示如何使用图像文件配置数据集仓库。您可以在图像数据集示例集合中找到随附的仓库示例。

具有支持的结构和文件格式的数据集在其 Hub 页面上自动拥有数据集查看器。

关于您的图像的附加信息 - 例如字幕或用于对象检测的边界框 - 只要您将此信息包含在元数据文件 (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 it's 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 it's 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

使用此结构创建的数据集包含两列:imagelabel(值为 greenred)。

您还可以提供多个拆分。为此,您的数据集目录应具有以下结构(有关更多信息,请参阅文件名和拆分

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

您可以在 YAML 配置中禁用自动添加 label 列。如果您的目录名称没有特殊含义,请在 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

请注意,为了方便用户并启用数据集查看器,Hub 中托管的每个数据集都会自动转换为 Parquet 格式(最大 5GB)。在Parquet 格式文档中阅读更多相关信息。

Parquet 格式

您可以将所有内容嵌入到 Parquet 文件中,而不是上传图像和元数据作为单独的文件。如果您有大量图像、想要嵌入多个图像列或想要在同一文件中存储关于图像的附加信息,这将非常有用。Parquet 也适用于存储原始字节等 JSON/CSV 不支持的数据。

my_dataset_repository/
└── train.parquet

可以使用 pandasdatasets 库创建包含图像数据的 Parquet 文件。要在 pandas 中创建包含图像数据的 Parquet 文件,您可以使用 pandas-image-methodsdf.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

请注意,对于小图像(每张图像 <1MB)和小行组(每行组 100 行,这是 datasets 用于图像的行数),建议使用 Parquet。对于较大的图像,建议使用 WebDataset 格式,或共享原始图像文件(可以选择使用元数据文件,并遵循 仓库建议和限制,了解存储和文件数量)。

< > 在 GitHub 上更新