# 图像数据集

本指南将向您展示如何配置包含图像文件的数据集仓库。您可以在这个[图像数据集示例集合](https://huggingface.co/collections/datasets-examples/image-dataset-6568e7cf28639db76eb92d65)中找到相关的仓库示例。

具有受支持的结构和[文件格式](./datasets-adding#file-formats)的数据集，其 Hub 页面会自动提供数据集查看器。

有关图像的其他信息 - 例如用于目标检测的说明或边界框 - 只要您将此信息包含在元数据文件（`metadata.csv`/`metadata.jsonl`/`metadata.parquet`）中，就会自动加载。

或者，图像可以存储在 Parquet 文件或遵循 [WebDataset](https://github.com/webdataset/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
```

同时支持多种[格式](./datasets-adding#file-formats)，包括 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
```

有关更多信息以及按 split 组织数据的其他方法，请参阅 [文件名和 split](./datasets-file-names-and-splits)。

## 附加列

如果您希望为数据集添加额外信息，例如文本说明或边界框，请在您的仓库中将其作为 `metadata.csv` 文件添加。这可以让您快速创建适用于不同计算机视觉任务的数据集，例如 [文本说明](https://huggingface.co/tasks/image-to-text) 或 [目标检测](https://huggingface.co/tasks/object-detection)。

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

您的 `metadata.csv` 文件必须包含一个 `file_name` 列，用于将图像文件与其元数据关联起来：

```csv
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](https://jsonlines.org/) 文件 `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](https://parquet.apache.org/) 文件 `metadata.parquet`。

## 相对路径

元数据文件必须位于与其关联的图像所在的同一目录中，或位于任意父目录中，如下例所示：

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

在这种情况下，`file_name` 列必须是图像的完整相对路径，而不仅仅是文件名：

```csv
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`）。

您也可以提供多个 split。为此，您的数据集目录应具有以下结构（有关更多信息，请参阅 [文件名和 split](./datasets-file-names-and-splits)）：

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

您可以在 [YAML 配置](./datasets-manual-configuration)中禁用自动添加 `label` 列的功能。如果您的目录名称没有特殊含义，请在 README 头部设置 `drop_labels: true`：

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

## 大规模数据集

### WebDataset 格式

[WebDataset](./datasets-webdataset) 格式非常适合大规模图像数据集（例如 [timm/imagenet-12k-wds](https://huggingface.co/datasets/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](./data-studio)，Hub 上托管的每个数据集都会自动转换为 Parquet 格式，上限为 5GB。有关此功能的更多信息，请参阅 [Parquet format](./data-studio#access-the-parquet-files) 文档。

### Parquet 格式

与其将图像和元数据作为单独的文件上传，您可以将所有内容嵌入到一个 [Parquet](https://parquet.apache.org/) 文件中。如果您拥有大量图像、希望嵌入多个图像列，或希望在同一文件中存储有关图像的附加信息，这种方式会非常有用。Parquet 还适用于存储原始字节等数据，而 JSON/CSV 并不支持此类数据。

```
my_dataset_repository/
└── train.parquet
```

可以使用 `pandas` 或 `datasets` 库创建包含图像数据的 Parquet 文件。要在 `pandas` 中创建包含图像数据的 Parquet 文件，可以使用 [pandas-image-methods](https://github.com/lhoestq/pandas-image-methods) 和 `df.to_parquet()`。在 `datasets` 中，可以将列类型设置为 `Image()`，并使用 `ds.to_parquet(...)` 方法或 `ds.push_to_hub(...)`。您可以在 `datasets` 的 [此处](/docs/datasets/image_load) 找到加载图像数据集的指南。

或者，您可以手动设置使用其他工具创建的 Parquet 文件的图像类型。首先，请确保您的图像列类型为 _struct_，其中包含一个用于图像数据的二进制字段 `"bytes"` 和一个用于图像文件名或路径的字符串字段 `"path"`。然后，您应该在 README 头部的 YAML 中直接指定这些列的特征类型，例如：

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

请注意，对于小图像（每张图像 <1MB）和小行组（每个行组 100 行，即 `datasets` 用于图像的设置），建议使用 Parquet 格式。对于较大的图像，建议使用 WebDataset 格式，或共享原始图像文件（可选地附带元数据文件，并遵循 [存储和文件数量的仓库建议与限制](https://huggingface.co/docs/hub/en/storage-limits)）。