資料集文件
載入
並獲得增強的文件體驗
開始使用
載入
您的資料可以儲存在不同的地方；例如：本機磁碟、Github 儲存庫，或是記憶體內的資料結構（如 Python 字典與 Pandas DataFrame）。無論資料集儲存在哪裡，🤗 Datasets 都能協助您將其載入。
本指南將展示如何從以下來源載入資料集：
- Hugging Face Hub
- 本機檔案
- 記憶體內資料
- 離線狀態
- 特定分割區的切片
若想深入了解如何載入其他類型的資料集，請參閱音訊資料集載入指南、圖像資料集載入指南、影片資料集載入指南，或是文字資料集載入指南。
Hugging Face Hub
您也可以從 Hub 上的任何資料集儲存庫載入資料集！首先請建立資料集儲存庫並上傳您的資料檔案。接著，您就可以使用 load_dataset() 函式來載入資料集。
例如，試著透過提供儲存庫命名空間與資料集名稱，從此範例儲存庫載入檔案。此資料集儲存庫包含 CSV 檔案，下方的程式碼會從這些 CSV 檔案中載入資料集：
>>> from datasets import load_dataset
>>> dataset = load_dataset("lhoestq/demo1")有些資料集可能會因為 Git 標籤（tags）、分支（branches）或提交（commits）而有多個版本。請使用 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 格式是嵌套欄位（nested field），這種情況下，您需要指定 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
與 CSV 等基於列（row-based）的檔案不同，Parquet 檔案以資料欄格式（columnar format）儲存。大型資料集可能會儲存在 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
與 CSV 等基於列的格式及 Parquet 等未壓縮格式不同，Arrow 檔案以記憶體內的資料欄格式儲存。
若要載入 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() 會以記憶體映射（memory maps）的方式載入 Arrow 檔案，而無需在快取中準備資料集，從而節省磁碟空間。在此情況下，儲存中間處理結果的快取目錄將會是 Arrow 檔案所在的目錄。
目前僅支援 Arrow 串流格式。不支援 Arrow IPC 檔案格式（也稱為 Feather V2）。
Lance
Lance 是一種用於 AI 的開源多模態 Lakehouse 表格格式。Lance 表格不僅能原生儲存文字與純量值，還能與您的表格資料並存儲存大型二進位物件（blobs），例如圖像、音訊與影片。
>>> from datasets import load_dataset
>>> lance_base_url = "lance-format/laion-1m"若要串流資料集而不將其複製到您的本機機器，請指定 streaming=True 參數。
ds = load_dataset(lance_base_url, split="train", streaming=True)
# Take first three rows
for row in ds.take(3):
print(row["caption"], row["image"])這將在單次請求中回傳圖像說明與圖像位元組。
HDF5 檔案
HDF5 檔案常用於科學計算與機器學習中儲存大量數值資料。使用 🤗 Datasets 載入 HDF5 檔案與載入 CSV 檔案相似。
>>> from datasets import load_dataset
>>> dataset = load_dataset("hdf5", data_files="data.h5")請注意，HDF5 載入器假設該檔案具有「表格」結構，即檔案中的所有資料集在其第一維度上具有（相同數量的）列。
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)遠端檔案
如果您有儲存為 csv、json、txt、parquet 或任何支援格式的遠端檔案，只要指定其遠端路徑，load_dataset() 函式即可載入它們。
- 公用線上檔案使用
https://URL，例如：data_files=["https://rajpurkar.github.io/SQuAD-explorer/dataset/train-v2.0.json"] - Hugging Face 上任何資料集儲存庫或儲存桶（Storage Bucket）中的檔案使用
hf://URL，例如：data_files=["hf://datasets/karpathy/tinystories-gpt4-clean/tinystories_gpt4_clean.parquet"]或data_files=["hf://buckets/julien-c/my-training-bucket/julien/affluence.csv"]
多重處理（Multiprocessing）
當資料集由多個檔案（我們稱為「分片/shards」）組成時，可以顯著加快資料集下載與準備的步驟。
您可以使用 num_proc 來選擇要使用多少處理程序（processes）並行準備資料集。在此情況下，每個處理程序會被分配到一部分的分片來進行準備。
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 DataFrame 等記憶體內資料結構中建立 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 shardsPandas 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 不會等待資料集產生器（builder）下載超時，而是會直接搜尋快取。將環境變數 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%:]")最後，您甚至可以建立交叉驗證（cross-validated）分割區。下方的範例建立 10 折（10-fold）交叉驗證分割區。每個驗證資料集為 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）。
指定特徵
當您從本機檔案建立資料集時，特徵（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'])}