加载

你的数据可以存储在不同的地方；它们可以位于你本地机器的磁盘上、Github 仓库中，以及内存中的数据结构中，如 Python 字典和 Pandas DataFrames。无论数据集存储在哪里，🤗 Datasets 都可以帮助你加载它。

本指南将向你展示如何从以下位置加载数据集

Hugging Face Hub
本地文件
内存数据
离线
拆分的特定切片
本地加载脚本 (旧版)

有关加载其他数据集模态的更多详细信息，请查看加载音频数据集指南、加载图像数据集指南、加载视频数据集指南或加载文本数据集指南。

Hugging Face Hub

数据集从数据集加载脚本加载，该脚本下载并生成数据集。但是，你也可以从 Hub 上的任何数据集仓库加载数据集，而无需加载脚本！首先创建一个数据集仓库并上传你的数据文件。现在你可以使用 load_dataset() 函数来加载数据集。

例如，尝试通过提供仓库命名空间和数据集名称，从这个演示仓库加载文件。此数据集仓库包含 CSV 文件，以下代码从 CSV 文件加载数据集

>>> from datasets import load_dataset
>>> dataset = load_dataset("lhoestq/demo1")

某些数据集可能基于 Git 标签、分支或提交有多个版本。使用 revision 参数指定你要加载的数据集版本

>>> dataset = load_dataset(
...   "lhoestq/custom_squad",
...   revision="main"  # tag name, or branch name, or commit hash
... )

有关如何在 Hub 上创建数据集仓库以及如何上传数据文件的更多详细信息，请参阅将数据集上传到 Hub 教程。

默认情况下，没有加载脚本的数据集会将所有数据加载到 train 拆分中。使用 data_files 参数将数据文件映射到 train、validation 和 test 等拆分

>>> data_files = {"train": "train.csv", "test": "test.csv"}
>>> dataset = load_dataset("namespace/your_dataset_name", data_files=data_files)

如果你不指定要使用哪些数据文件，load_dataset() 将返回所有数据文件。如果你加载像 C4 这样的大型数据集（大约 13TB 数据），这可能需要很长时间。

你还可以使用 data_files 或 data_dir 参数加载文件的特定子集。这些参数可以接受相对于数据集加载位置的基本路径的相对路径。

>>> from datasets import load_dataset

# load files that match the grep pattern
>>> c4_subset = load_dataset("allenai/c4", data_files="en/c4-train.0000*-of-01024.json.gz")

# load dataset from the en directory on the Hub
>>> c4_subset = load_dataset("allenai/c4", data_dir="en")

split 参数还可以将数据文件映射到特定的拆分

>>> data_files = {"validation": "en/c4-validation.*.json.gz"}
>>> c4_validation = load_dataset("allenai/c4", data_files=data_files, split="validation")

本地和远程文件

数据集可以从存储在你计算机上的本地文件和远程文件加载。数据集最有可能存储为 csv、json、txt 或 parquet 文件。load_dataset() 函数可以加载这些文件类型中的每一种。

CSV

🤗 Datasets 可以读取由一个或多个 CSV 文件组成的数据集（在这种情况下，将你的 CSV 文件作为列表传递）

>>> from datasets import load_dataset
>>> dataset = load_dataset("csv", data_files="my_file.csv")

有关更多详细信息，请查看如何从 CSV 文件加载表格数据集指南。

JSON

JSON 文件可以直接使用 load_dataset() 加载，如下所示

>>> from datasets import load_dataset
>>> dataset = load_dataset("json", data_files="my_file.json")

JSON 文件有多种格式，但我们认为最有效的格式是具有多个 JSON 对象；每行代表数据的单个行。例如

{"a": 1, "b": 2.0, "c": "foo", "d": false}
{"a": 4, "b": -5.5, "c": null, "d": true}

你可能遇到的另一种 JSON 格式是嵌套字段，在这种情况下，你需要指定 field 参数，如下所示

{"version": "0.1.0",
 "data": [{"a": 1, "b": 2.0, "c": "foo", "d": false},
          {"a": 4, "b": -5.5, "c": null, "d": true}]
}

>>> from datasets import load_dataset
>>> dataset = load_dataset("json", data_files="my_file.json", field="data")

要通过 HTTP 加载远程 JSON 文件，请传递 URL

>>> base_url = "https://rajpurkar.github.io/SQuAD-explorer/dataset/"
>>> dataset = load_dataset("json", data_files={"train": base_url + "train-v1.1.json", "validation": base_url + "dev-v1.1.json"}, field="data")

虽然这些是最常见的 JSON 格式，但你会看到其他格式不同的数据集。🤗 Datasets 识别这些其他格式，并将相应地回退到 Python JSON 加载方法来处理它们。

Parquet

Parquet 文件以列式格式存储，这与基于行的文件（如 CSV）不同。大型数据集可以存储在 Parquet 文件中，因为它在返回查询时更高效、更快速。

要加载 Parquet 文件

>>> from datasets import load_dataset
>>> dataset = load_dataset("parquet", data_files={'train': 'train.parquet', 'test': 'test.parquet'})

要通过 HTTP 加载远程 Parquet 文件，请传递 URL

>>> base_url = "https://huggingface.co/datasets/wikimedia/wikipedia/resolve/main/20231101.ab/"
>>> data_files = {"train": base_url + "train-00000-of-00001.parquet"}
>>> wiki = load_dataset("parquet", data_files=data_files, split="train")

Arrow

Arrow 文件以内存列式格式存储，这与基于行的格式（如 CSV）和未压缩的格式（如 Parquet）不同。

要加载 Arrow 文件

>>> from datasets import load_dataset
>>> dataset = load_dataset("arrow", data_files={'train': 'train.arrow', 'test': 'test.arrow'})

要通过 HTTP 加载远程 Arrow 文件，请传递 URL

>>> base_url = "https://huggingface.co/datasets/croissantllm/croissant_dataset/resolve/main/english_660B_11/"
>>> data_files = {"train": base_url + "train/data-00000-of-00080.arrow"}
>>> wiki = load_dataset("arrow", data_files=data_files, split="train")

Arrow 是 🤗 Datasets 在底层使用的文件格式，因此你可以直接使用 Dataset.from_file() 加载本地 Arrow 文件

>>> from datasets import Dataset
>>> dataset = Dataset.from_file("data.arrow")

与 load_dataset() 不同，Dataset.from_file() 内存映射 Arrow 文件，而无需在缓存中准备数据集，从而节省磁盘空间。在这种情况下，用于存储中间处理结果的缓存目录将是 Arrow 文件目录。

目前仅支持 Arrow 流式传输格式。不支持 Arrow IPC 文件格式（也称为 Feather V2）。

SQL

通过指定 URI 连接到你的数据库，使用 from_sql() 读取数据库内容。你可以读取表名和查询

>>> from datasets import Dataset
# load entire table
>>> dataset = Dataset.from_sql("data_table_name", con="sqlite:///sqlite_file.db")
# load from query
>>> dataset = Dataset.from_sql("SELECT text FROM table WHERE length(text) > 100 LIMIT 10", con="sqlite:///sqlite_file.db")

有关更多详细信息，请查看如何从 SQL 数据库加载表格数据集指南。

WebDataset

WebDataset 格式基于 TAR 归档，适用于大型图像数据集。由于它们的大小，WebDatasets 通常以流式模式加载（使用 streaming=True）。

你可以像这样加载 WebDataset

>>> from datasets import load_dataset
>>>
>>> path = "path/to/train/*.tar"
>>> dataset = load_dataset("webdataset", data_files={"train": path}, split="train", streaming=True)

要通过 HTTP 加载远程 WebDatasets，请传递 URL

>>> from datasets import load_dataset
>>>
>>> base_url = "https://huggingface.co/datasets/lhoestq/small-publaynet-wds/resolve/main/publaynet-train-{i:06d}.tar"
>>> urls = [base_url.format(i=i) for i in range(4)]
>>> dataset = load_dataset("webdataset", data_files={"train": urls}, split="train", streaming=True)

多进程

当数据集由多个文件（我们称之为“分片”）组成时，可以显着加快数据集下载和准备步骤。

你可以选择要使用多少进程并行准备数据集，使用 num_proc。在这种情况下，每个进程都会获得要准备的分片子集

from datasets import load_dataset

imagenet = load_dataset("timm/imagenet-1k-wds", num_proc=8)
ml_librispeech_spanish = load_dataset("facebook/multilingual_librispeech", "spanish", num_proc=8)

内存数据

🤗 Datasets 还允许你直接从内存数据结构（如 Python 字典和 Pandas DataFrames）创建 Dataset。

Python 字典

使用 from_dict() 加载 Python 字典

>>> from datasets import Dataset
>>> my_dict = {"a": [1, 2, 3]}
>>> dataset = Dataset.from_dict(my_dict)

Python 字典列表

使用 from_list() 加载 Python 字典列表

>>> from datasets import Dataset
>>> my_list = [{"a": 1}, {"a": 2}, {"a": 3}]
>>> dataset = Dataset.from_list(my_list)

Python 生成器

使用 from_generator() 从 Python 生成器创建数据集

>>> from datasets import Dataset
>>> def my_gen():
...     for i in range(1, 4):
...         yield {"a": i}
...
>>> dataset = Dataset.from_generator(my_gen)

这种方法支持加载大于可用内存的数据。

您还可以通过将列表传递给 gen_kwargs 来定义分片数据集。

>>> def gen(shards):
...     for shard in shards:
...         with open(shard) as f:
...             for line in f:
...                 yield {"line": line}
...
>>> shards = [f"data{i}.txt" for i in range(32)]
>>> ds = IterableDataset.from_generator(gen, gen_kwargs={"shards": shards})
>>> ds = ds.shuffle(seed=42, buffer_size=10_000)  # shuffles the shards order + uses a shuffle buffer
>>> from torch.utils.data import DataLoader
>>> dataloader = DataLoader(ds.with_format("torch"), num_workers=4)  # give each worker a subset of 32/4=8 shards

Pandas DataFrame

使用 from_pandas() 加载 Pandas DataFrame

>>> from datasets import Dataset
>>> import pandas as pd
>>> df = pd.DataFrame({"a": [1, 2, 3]})
>>> dataset = Dataset.from_pandas(df)

更多详情，请查看如何从 Pandas DataFrame 加载表格数据集指南。

离线

即使您没有互联网连接，仍然可以加载数据集。只要您之前从 Hub 仓库下载过数据集，它就应该被缓存。这意味着您可以从缓存中重新加载数据集并离线使用。

如果您知道您将无法访问互联网，您可以以完全离线模式运行 🤗 Datasets。这样做可以节省时间，因为 🤗 Datasets 将直接在缓存中查找，而不是等待 Dataset 构建器下载超时。将环境变量 HF_HUB_OFFLINE 设置为 1 以启用完全离线模式。

切片分割

您还可以选择仅加载分割的特定切片。有两种分割切片的方式：使用字符串或 ReadInstruction API。对于简单的情况，字符串更简洁易读，而 ReadInstruction 更容易用于可变的切片参数。

通过以下方式连接 train 和 test 分割


>>> train_test_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train+test")

选择 train 分割的特定行


>>> train_10_20_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[10:20]")

或使用以下方式选择分割的百分比


>>> train_10pct_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[:10%]")

从每个分割中选择百分比的组合


>>> train_10_80pct_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[:10%]+train[-80%:]")

最后，您甚至可以创建交叉验证分割。下面的示例创建了 10 折交叉验证分割。每个验证数据集是一个 10% 的块，而训练数据集构成剩余的互补 90% 的块。


>>> val_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=[f"train[{k}%:{k+10}%]" for k in range(0, 100, 10)])
>>> train_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=[f"train[:{k}%]+train[{k+10}%:]" for k in range(0, 100, 10)])

百分比切片和舍入

对于请求的切片边界不能被 100 整除的数据集，默认行为是将边界四舍五入到最接近的整数。如下所示，某些切片可能包含比其他切片更多的示例。例如，如果以下 train 分割包含 999 条记录，则：

# 19 records, from 500 (included) to 519 (excluded).
>>> train_50_52_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[50%:52%]")
# 20 records, from 519 (included) to 539 (excluded).
>>> train_52_54_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[52%:54%]")

如果您想要大小相等的分割，请改用 pct1_dropremainder 舍入。这会将指定的百分比边界视为 1% 的倍数。

# 18 records, from 450 (included) to 468 (excluded).
>>> train_50_52pct1_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=datasets.ReadInstruction("train", from_=50, to=52, unit="%", rounding="pct1_dropremainder"))
# 18 records, from 468 (included) to 486 (excluded).
>>> train_52_54pct1_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split=datasets.ReadInstruction("train",from_=52, to=54, unit="%", rounding="pct1_dropremainder"))
# Or equivalently:
>>> train_50_52pct1_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[50%:52%](pct1_dropremainder)")
>>> train_52_54pct1_ds = datasets.load_dataset("ajibawa-2023/General-Stories-Collection", split="train[52%:54%](pct1_dropremainder)")

如果数据集中的示例数量不能被 100 整除，pct1_dropremainder 舍入可能会截断数据集中的最后几个示例。

故障排除

有时，当您加载数据集时，可能会得到意外的结果。您可能遇到的两个最常见的问题是手动下载数据集和指定数据集的特征。

指定特征

当您从本地文件创建数据集时，Features 由 Apache Arrow 自动推断。但是，数据集的特征可能并不总是符合您的预期，或者您可能想要自己定义特征。以下示例展示了如何使用 ClassLabel 特征添加自定义标签。

首先使用 Features 类定义您自己的标签

>>> class_names = ["sadness", "joy", "love", "anger", "fear", "surprise"]
>>> emotion_features = Features({'text': Value('string'), 'label': ClassLabel(names=class_names)})

接下来，在 load_dataset() 中使用您刚刚创建的特征指定 features 参数

>>> dataset = load_dataset('csv', data_files=file_dict, delimiter=';', column_names=['text', 'label'], features=emotion_features)

现在，当您查看数据集特征时，您可以看到它使用了您定义的自定义标签

>>> dataset['train'].features
{'text': Value(dtype='string', id=None),
'label': ClassLabel(names=['sadness', 'joy', 'love', 'anger', 'fear', 'surprise'], id=None)}

（旧版）本地加载脚本

您可能在本地计算机上有一个 🤗 Datasets 加载脚本。在这种情况下，通过将以下路径之一传递给 load_dataset() 来加载数据集

加载脚本文件的本地路径。
包含加载脚本文件的目录的本地路径（仅当脚本文件与目录同名时）。

传递 trust_remote_code=True 以允许 🤗 Datasets 执行加载脚本

>>> dataset = load_dataset("path/to/local/loading_script/loading_script.py", split="train", trust_remote_code=True)
>>> dataset = load_dataset("path/to/local/loading_script", split="train", trust_remote_code=True)  # equivalent because the file has the same name as the directory

< > 在 GitHub 上更新