載入

您的資料可以儲存在各種地方；它們可以在本地機器的磁碟上、在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 分割中，或者檢查資料檔名稱中是否有提及或分割名稱（例如“train”、“test”和“validation”）。使用 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

使用from_sql()讀取資料庫內容，透過指定連線資料庫的 URI。您可以讀取表名和查詢：

>>> 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 歸檔，適用於大型影像資料集。由於其大小，WebDataset 通常以流式模式載入（使用 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 載入遠端 WebDataset，請傳遞 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 DataFrames：

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

有關更多詳細資訊，請檢視如何從 Pandas DataFrames 載入表格資料集指南。

離線

即使沒有網際網路連線，仍然可以載入資料集。只要您之前從 Hub 倉庫下載過資料集，它就應該被快取。這意味著您可以從快取重新載入資料集並離線使用它。

如果您知道沒有網際網路連線，可以以完全離線模式執行 🤗 Datasets。這可以節省時間，因為無需等待資料集構建器下載超時，🤗 Datasets 將直接在快取中查詢。將環境變數 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 整除的資料集。如下所示，有些切片可能包含比其他切片更多的示例。例如，如果以下訓練集包含 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('string'),
'label': ClassLabel(names=['sadness', 'joy', 'love', 'anger', 'fear', 'surprise'])}

< > 在 GitHub 上更新