# 创建文档数据集

本指南将展示如何使用 `PdfFolder` 创建包含若干元数据的文档数据集。这是一种无需编写代码的方案，可快速创建包含数千个 PDF 的文档数据集。

> [!TIP]
> 您可以通过要求用户先共享其联系信息来控制对数据集的访问权限。有关如何在 Hub 上启用此功能的更多信息，请参阅 [Gated datasets](https://huggingface.co/docs/hub/datasets-gated) 指南。

## PdfFolder

`PdfFolder` 是一个数据集构建器，旨在快速加载包含数千个 PDF 的文档数据集，且无需编写任何代码。

> [!TIP]
> 💡 查看 [Split pattern hierarchy](repository_structure#split-pattern-hierarchy) 以了解 `PdfFolder` 如何根据数据集仓库结构创建数据集拆分。

`PdfFolder` 会根据目录名称自动推断数据集的类别标签。请将数据集存储在如下目录结构中：

```
folder/train/resume/0001.pdf
folder/train/resume/0002.pdf
folder/train/resume/0003.pdf

folder/train/invoice/0001.pdf
folder/train/invoice/0002.pdf
folder/train/invoice/0003.pdf
```

如果数据集遵循 `PdfFolder` 结构，则可以直接使用 [load_dataset()](/docs/datasets/main/zh/package_reference/loading_methods#datasets.load_dataset) 加载：

```py
>>> from datasets import load_dataset

>>> dataset = load_dataset("path/to/folder")
```

这相当于在 [load_dataset()](/docs/datasets/main/zh/package_reference/loading_methods#datasets.load_dataset) 中手动传入 `pdffolder` 以及 `data_dir` 中的目录：

```py
>>> dataset = load_dataset("pdffolder", data_dir="/path/to/folder")
```

您还可以使用 `pdffolder` 来加载涉及多个拆分的数据集。为此，您的数据集目录应具有以下结构：

```
folder/train/resume/0001.pdf
folder/train/resume/0002.pdf
folder/test/invoice/0001.pdf
folder/test/invoice/0002.pdf
```

> [!WARNING]
> 如果所有 PDF 文件都位于同一个目录中，或者它们不在同一层级的目录结构中，则不会自动添加`label`列。如果需要该列，请显式设置`drop_labels=False`。

如果您希望为数据集添加额外信息，例如文本说明或边界框，请在您的文件夹中将其添加为 `metadata.csv` 文件。这可以让您快速创建用于不同计算机视觉任务的数据集，例如文本说明或目标检测。您也可以使用 JSONL 文件 `metadata.jsonl` 或 Parquet 文件 `metadata.parquet`。

```
folder/train/metadata.csv
folder/train/0001.pdf
folder/train/0002.pdf
folder/train/0003.pdf
```

您的 `metadata.csv` 文件必须包含一个 `file_name` 或 `*_file_name` 字段，用于将 PDF 文件与其元数据关联起来：

```csv
file_name,additional_feature
0001.pdf,This is a first value of a text feature you added to your pdfs
0002.pdf,This is a second value of a text feature you added to your pdfs
0003.pdf,This is a third value of a text feature you added to your pdfs
```

或使用 `metadata.jsonl`：

```jsonl
{"file_name": "0001.pdf", "additional_feature": "This is a first value of a text feature you added to your PDFs"}
{"file_name": "0002.pdf", "additional_feature": "This is a second value of a text feature you added to your PDFs"}
{"file_name": "0003.pdf", "additional_feature": "This is a third value of a text feature you added to your PDFs"}
```

此处 `file_name` 必须是位于元数据文件旁边的 PDF 文件的名称。更一般地，它必须是包含元数据的目录到 PDF 文件的相对路径。

在数据集中的每一行中，可以指向多个 PDF，例如当输入和输出都是 PDF 时：

```jsonl
{"input_file_name": "0001.pdf", "output_file_name": "0001_output.pdf"}
{"input_file_name": "0002.pdf", "output_file_name": "0002_output.pdf"}
{"input_file_name": "0003.pdf", "output_file_name": "0003_output.pdf"}
```

您还可以定义 PDF 列表。在这种情况下，您需要将该字段命名为 `file_names` 或 `*_file_names`。示例如下：

```jsonl
{"pdfs_file_names": ["0001_part1.pdf", "0001_part2.pdf"], "label": "urgent"}
{"pdfs_file_names": ["0002_part1.pdf", "0002_part2.pdf"], "label": "urgent"}
{"pdfs_file_names": ["0003_part1.pdf", "0002_part2.pdf"], "label": "normal"}
```

### OCR (光学字符识别)

OCR 数据集包含 PDF 中的文本。`metadata.csv` 示例可能如下所示：

```csv
file_name,text
0001.pdf,Invoice 1234 from 01/01/1970...
0002.pdf,Software Engineer Resume. Education: ...
0003.pdf,Attention is all you need. Abstract. The ...
```

使用 `PdfFolder` 加载数据集，它将创建一个 `text` 列用于 PDF 说明：

```py
>>> dataset = load_dataset("pdffolder", data_dir="/path/to/folder", split="train")
>>> dataset[0]["text"]
"Invoice 1234 from 01/01/1970..."
```

### 将数据集上传到 Hub

创建数据集后，您可以使用例如 `huggingface_hub` 进行共享。请确保已安装 [huggingface_hub](https://huggingface.co/docs/huggingface_hub/index) 库，并已登录您的 Hugging Face 账户（更多详情请参阅 [Upload with Python tutorial](upload_dataset#upload-with-python)）。

使用 `huggingface_hub.HfApi.upload_folder` 上传您的数据集：

```py
from huggingface_hub import HfApi
api = HfApi()

api.upload_folder(
    folder_path="/path/to/local/dataset",
    repo_id="username/my-cool-dataset",
    repo_type="dataset",
)
```