Tải

Dữ liệu của bạn có thể được lưu trữ ở nhiều vị trí khác nhau; chúng có thể nằm trên ổ đĩa của máy cục bộ, trong một kho lưu trữ Github, và trong các cấu trúc dữ liệu trong bộ nhớ như từ điển Python và DataFrame Pandas. Bất kể dataset được lưu ở đâu, 🤗 Datasets đều có thể giúp bạn nạp nó.

Hướng dẫn này sẽ cho bạn thấy cách tải một tập dữ liệu từ:

• Hugging Face Hub
• Tệp cục bộ
• Dữ liệu trong bộ nhớ
• Ngoại tuyến
• Một lát cắt cụ thể của một phần chia

Để biết thêm chi tiết cụ thể về việc tải các chế độ dữ liệu khác, hãy xem hướng dẫn tải bộ dữ liệu âm thanh, hướng dẫn tải bộ dữ liệu hình ảnh, hướng dẫn tải bộ dữ liệu video, hướng dẫn tải bộ dữ liệu lưới, hướng dẫn tải bộ dữ liệu văn bản hoặc hướng dẫn tải các tác vụ đánh giá agent.

Hugging Face Hub

Bạn cũng có thể tải một dataset từ bất kỳ kho dataset nào trên Hub! Hãy bắt đầu bằng cách tạo một kho dataset và tải lên các tệp dữ liệu của bạn. Bây giờ bạn có thể sử dụng hàm load_dataset() để tải dataset.

Ví dụ, hãy thử tải các tệp từ kho demo này bằng cách cung cấp không gian tên của kho và tên bộ dữ liệu. Kho bộ dữ liệu này chứa các tệp CSV, và đoạn mã bên dưới sẽ tải bộ dữ liệu từ các tệp CSV:

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

Một số tập dữ liệu có thể có nhiều hơn một phiên bản dựa trên các thẻ Git, nhánh hoặc commit. Sử dụng tham số revision để chỉ định phiên bản tập dữ liệu mà bạn muốn tải:

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

Tham khảo hướng dẫn Tải lên Hub một bộ dữ liệu để biết thêm chi tiết về cách tạo kho dữ liệu trên Hub và cách tải lên các tệp dữ liệu của bạn.

Một dataset mặc định sẽ nạp toàn bộ dữ liệu vào split train, hoặc kiểm tra các tên split được đề cập trong tên tệp dữ liệu (ví dụ: “train”, “test” và “validation”). Sử dụng tham số data_files để ánh xạ các tệp dữ liệu vào các split như train, validation và test:

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

Nếu bạn không chỉ định các tệp dữ liệu cần sử dụng, load_dataset() sẽ trả về tất cả các tệp dữ liệu. Điều này có thể mất rất nhiều thời gian nếu bạn tải một bộ dữ liệu lớn như C4, với dung lượng khoảng 13TB.

Bạn cũng có thể tải một tập con cụ thể của các tệp bằng tham số data_files hoặc data_dir. Các tham số này có thể nhận một đường dẫn tương đối, được phân giải thành đường dẫn cơ sở tương ứng với nơi bộ dữ liệu được tải từ đó.

>>> 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")

Tham số split cũng có thể ánh xạ một tệp dữ liệu đến một split cụ thể:

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

Tệp cục bộ và từ xa

Dữ liệu có thể được tải từ các tệp cục bộ lưu trên máy tính của bạn và từ các tệp từ xa. Dữ liệu thường được lưu dưới dạng tệp csv, json, txt, parquet hoặc tsfile. Hàm load_dataset() có thể tải từng loại tệp này.

CSV

🤗 Datasets có thể đọc một tập dữ liệu gồm một hoặc nhiều tệp CSV (trong trường hợp này, hãy truyền các tệp CSV của bạn dưới dạng một danh sách):

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

Để biết thêm chi tiết, hãy xem hướng dẫn cách tải bộ dữ liệu bảng từ tệp CSV.

JSON

Các tệp JSON được tải trực tiếp bằng load_dataset() như minh họa bên dưới:

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

Các tệp JSON có nhiều định dạng khác nhau, nhưng chúng tôi cho rằng định dạng hiệu quả nhất là có nhiều đối tượng JSON; mỗi dòng đại diện cho một hàng dữ liệu riêng lẻ. Ví dụ:

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

Một định dạng JSON khác mà bạn có thể gặp là trường lồng nhau, trong trường hợp đó bạn sẽ cần chỉ định đối số field như được minh họa bên dưới:

{"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")

Để tải các tệp JSON từ xa qua HTTP, hãy truyền các URL thay vào đó:

>>> 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")

Mặc dù đây là các định dạng JSON phổ biến nhất, bạn sẽ thấy các bộ dữ liệu khác được định dạng khác nhau. 🤗 Datasets nhận diện các định dạng khác này và sẽ tự động chuyển sang các phương thức nạp JSON của Python để xử lý chúng.

Parquet

File Parquet được lưu trữ ở định dạng cột, khác với các file dựa trên hàng như CSV. Các bộ dữ liệu lớn có thể được lưu trong file Parquet vì định dạng này hiệu quả và nhanh hơn khi trả về truy vấn của bạn.

Để tải một tệp Parquet:

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

Để tải các tệp Parquet từ xa qua HTTP, hãy truyền các URL thay vào đó:

>>> 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

Các tệp Arrow được lưu trữ ở định dạng cột trong bộ nhớ, khác với các định dạng dựa trên hàng như CSV và các định dạng không nén như Parquet.

Để tải một tệp Arrow:

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

Để tải các tệp Arrow từ xa qua HTTP, hãy truyền các URL thay vào đó:

>>> 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 là định dạng tệp được sử dụng bởi 🤗 Datasets bên trong, do đó bạn có thể tải một tệp Arrow cục bộ bằng cách sử dụng trực tiếp Dataset.from_file():

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

Khác với load_dataset(), Dataset.from_file() ánh xạ bộ nhớ (memory map) tệp Arrow mà không chuẩn bị bộ dữ liệu trong bộ nhớ đệm, giúp tiết kiệm dung lượng ổ đĩa. Trong trường hợp đó, thư mục bộ nhớ đệm để lưu trữ kết quả xử lý trung gian sẽ là thư mục chứa tệp Arrow.

Hiện tại chỉ hỗ trợ định dạng streaming Arrow. Định dạng tệp Arrow IPC (còn được gọi là Feather V2) không được hỗ trợ.

Lance

Lance là định dạng bảng lakehouse đa phương thức mã nguồn mở dành cho AI. Các bảng Lance có thể lưu trữ bản địa không chỉ văn bản và giá trị vô hướng mà còn cả các đối tượng nhị phân lớn (blobs) như hình ảnh, âm thanh và video cùng với dữ liệu bảng của bạn.

>>> from datasets import load_dataset
>>> lance_base_url = "lance-format/laion-1m"

Để stream bộ dữ liệu mà không sao chép nó về máy cục bộ, hãy chỉ định tham số 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"])

Điều này sẽ trả về chú thích hình ảnh và các byte của hình ảnh trong một yêu cầu duy nhất.

Vortex

Vortex là định dạng tệp cột được xây dựng để quét nhanh trên dữ liệu nén. Cài đặt bằng pip install vortex-data, sau đó tải các tệp .vortex như bất kỳ định dạng đóng gói nào khác:

>>> from datasets import load_dataset
>>> dataset = load_dataset("vortex", data_files="data.vortex", split="train")

Các cột và bộ lọc được đẩy xuống (push down) vào quá trình quét Vortex, nên chỉ có các hàng và cột bạn yêu cầu mới được đọc. Cơ chế này hoạt động cả khi streaming, cho phép bạn lọc một dataset trên Hub mà không cần tải về các phần không khớp:

>>> filters = [("label", "==", 1)]
>>> dataset = load_dataset(vortex_dataset_id, columns=["text", "label"], filters=filters, streaming=True, split="train")

Bộ lọc sử dụng cùng dạng chuẩn tách biệt (disjunctive normal form) như trình nạp Parquet: một danh sách các điều kiện (column, operator, value) là một phép hội, và một danh sách các danh sách đó là một phép tuyển. Giá trị null tuân theo ngữ nghĩa SQL — một giá trị null không thỏa mãn bất kỳ phép so sánh nào, do đó một hàng có cột được lọc là null sẽ không bao giờ được trả về, kể cả với not in. Đối với bất kỳ điều gì mà dạng đó không thể biểu diễn, hãy truyền một biểu thức Vortex thay thế:

>>> import vortex.expr as ve
>>> dataset = load_dataset(vortex_dataset_id, filters=ve.column("score") >= 0.5, split="train")

Vortex tự mở tệp thay vì thông qua fsspec, do đó data_files có thể trỏ đến các đường dẫn cục bộ, bộ dữ liệu Hub và các vị trí từ xa mà Vortex đọc một cách bản địa (HTTP và các kho lưu trữ đối tượng phổ biến) — nhưng không phải bên trong các tệp lưu trữ (zip://...) hoặc các giao thức chỉ có trong fsspec.

Tệp HDF5

HDF5 thường được dùng để lưu trữ lượng lớn dữ liệu số trong tính toán khoa học và học máy. Việc tải tệp HDF5 bằng 🤗 Datasets tương tự như tải tệp CSV:

>>> from datasets import load_dataset
>>> dataset = load_dataset("hdf5", data_files="data.h5")

Lưu ý rằng trình nạp HDF5 giả định rằng tệp có cấu trúc “bảng”, tức là tất cả các tập dữ liệu trong tệp đều có (số hàng giống nhau) trên chiều đầu tiên.

TsFile

TsFile là định dạng tệp dạng cột được thiết kế cho dữ liệu chuỗi thời gian, được sử dụng làm lớp lưu trữ gốc của Apache IoTDB. Nó biểu diễn bản địa các mốc thời gian, thẻ thiết bị và trường đo lường, đồng thời duy trì một chỉ mục thời gian nội bộ cho phép loại bỏ hiệu quả các khoảng thời gian.

Mỗi hàng trong dataset kết quả tương ứng với một device (được xác định bởi các cột TAG); cột time và mọi cột FIELD là các cột danh sách chứa toàn bộ chuỗi thời gian của device đó, được sắp xếp theo thứ tự thời gian tăng dần.

Để tải một TsFile:

>>> from datasets import load_dataset
>>> dataset = load_dataset("tsfile", data_files="my_data.tsfile")

Lọc theo khoảng thời gian — các giới hạn được đẩy xuống chỉ mục thời gian nội bộ của TsFile và chấp nhận epoch dạng int, datetime, date, chuỗi ISO-8601, hoặc các giá trị timestamp của pyarrow:

>>> from datetime import datetime
>>> dataset = load_dataset(
...     "tsfile",
...     data_files="my_data.tsfile",
...     start_time=datetime(2023, 11, 14),
...     end_time=datetime(2023, 11, 15),
... )

Để biết thêm chi tiết, hãy xem hướng dẫn cách tải dữ liệu TsFile.

Harbor

Bộ dữ liệu Harbor là các tập hợp task được dùng để đánh giá các AI agent. Chúng được cấu thành từ các thư mục thay vì các tệp dữ liệu: mỗi task là một thư mục chứa tệp cấu hình task.toml và tệp instruction.md, cùng với môi trường, bộ xác minh và giải pháp của nó.

Mỗi hàng của tập dữ liệu kết quả mô tả một tác vụ (lệnh của nó, task.toml của nó, các tệp đi kèm), và việc nạp nó không bao giờ thực thi bất kỳ thứ gì:

>>> from datasets import load_dataset
>>> dataset = load_dataset("harborframework/terminal-bench")
>>> dataset["train"][0]["task_id"]
'tasks/atrx-vep-crispr'

Để biết thêm chi tiết, hãy xem hướng dẫn cách tải các tác vụ đánh giá agent.

PDB

PDB (Protein Data Bank) là định dạng cố định chiều rộng cũ để biểu diễn các cấu trúc đại phân tử 3D. Trong khi mmCIF là tiêu chuẩn hiện đại, PDB vẫn được sử dụng rộng rãi và nhiều bộ dữ liệu lịch sử ở định dạng này.

Mỗi hàng là một tệp cấu trúc, tuân theo cùng bố cục thư mục như ImageFolder: tên thư mục con trở thành nhãn và tệp metadata.csv/metadata.jsonl bổ sung metadata cho từng cấu trúc. Cột structure sử dụng BioStructure với format="pdb" và giải mã thành đối tượng Bio.PDB.Structure.Structure chứa các model, chuỗi, residue và nguyên tử của tệp. Việc giải mã yêu cầu biopython; nếu không có, việc truy cập một cấu trúc đã giải mã sẽ gây ra ImportError.

Để tải các tệp PDB từ một thư mục:

>>> from datasets import BioStructure, load_dataset
>>> dataset = load_dataset("pdb", data_dir="path/to/structures")
>>> dataset["train"].features["structure"]
BioStructure(format='pdb', decode=True)

Để truy cập từ điển {"bytes": ..., "path": ...} bên dưới mà không cần giải mã hoặc yêu cầu biopython, hãy chuyển kiểu cột với decode=False:

>>> dataset = dataset.cast_column("structure", BioStructure(format="pdb", decode=False))

Các phần mở rộng .pdb và .ent được hỗ trợ.

SQL

Đọc nội dung cơ sở dữ liệu bằng from_sql() bằng cách chỉ định URI để kết nối với cơ sở dữ liệu của bạn. Bạn có thể đọc cả tên bảng và truy vấn:

>>> 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")

Để biết thêm chi tiết, hãy xem hướng dẫn cách tải bộ dữ liệu bảng từ cơ sở dữ liệu SQL.

WebDataset

Định dạng WebDataset dựa trên các tệp lưu trữ TAR và phù hợp cho các bộ dữ liệu ảnh lớn. Do kích thước của chúng, WebDataset thường được tải ở chế độ streaming (sử dụng streaming=True).

Bạn có thể nạp một WebDataset như sau:

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

Để nạp các WebDatasets từ xa qua HTTP, hãy truyền các URL thay vào đó:

>>> 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)

mmCIF

mmCIF (tệp thông tin tinh thể học đại phân tử) là định dạng chuẩn hiện đại để biểu diễn các cấu trúc đại phân tử 3D, được Ngân hàng Dữ liệu Protein (PDB) sử dụng từ năm 2014.

Mỗi hàng là một tệp cấu trúc, tuân theo cùng bố cục thư mục như ImageFolder: tên thư mục con trở thành nhãn và tệp metadata.csv/metadata.jsonl bổ sung metadata cho từng cấu trúc. Cột structure sử dụng BioStructure với format="mmcif" và giải mã thành đối tượng Bio.PDB.Structure.Structure chứa các model, chuỗi, residue và nguyên tử của tệp. Việc giải mã yêu cầu biopython; nếu không có, việc truy cập một cấu trúc đã giải mã sẽ gây ra ImportError.

Để tải các tệp mmCIF từ một thư mục:

>>> from datasets import BioStructure, load_dataset
>>> dataset = load_dataset("mmcif", data_dir="path/to/structures")
>>> dataset["train"].features["structure"]
BioStructure(format='mmcif', decode=True)

Để truy cập từ điển {"bytes": ..., "path": ...} bên dưới mà không cần giải mã hoặc yêu cầu biopython, hãy chuyển kiểu cột với decode=False:

>>> dataset = dataset.cast_column("structure", BioStructure(format="mmcif", decode=False))

Các phần mở rộng .cif và .mmcif được hỗ trợ.

GenBank

GenBank là định dạng dựa trên văn bản từ NCBI dành cho các trình tự nucleotide và protein cùng với chú giải của chúng. Các tệp sử dụng phần mở rộng .gb, .gbk hoặc .genbank (có thể nén tùy chọn), và phần FEATURES của mỗi bản ghi được giải mã thành các đối tượng có cấu trúc.

Bên cạnh các cột đã phân tích nhẹ, mỗi hàng bao gồm một cột record có kiểu BioSequence(format="genbank"), được giải mã thành Bio.SeqRecord.SeqRecord khi biopython được cài đặt. Ép kiểu cột này thành BioSequence(format="genbank", decode=False) để truy cập các byte của bản ghi gốc dưới dạng {"bytes": ..., "path": None}, hoặc bỏ qua nó bằng columns=[...] để chỉ sử dụng các cột đã phân tích mà không cần biopython.

Để tải các tệp GenBank:

>>> from datasets import load_dataset
>>> dataset = load_dataset("genbank", data_files="*.gb", split="train")

Bạn có thể thử trên một tập dữ liệu nhỏ gồm các bản ghi NCBI thực tế (một trong số đó được nén bằng gzip để cho thấy các tệp nén được nạp một cách trong suốt):

>>> from datasets import load_dataset
>>> dataset = load_dataset("ermiaazarkhalili/datasets-genbank-test", data_files="*.gb*", split="train")
>>> dataset[0]["locus_name"], dataset[0]["organism"], dataset[0]["length"]

FASTQ

FASTQ là định dạng dựa trên văn bản để lưu trữ các trình tự nucleotide cùng với điểm chất lượng của chúng, được sử dụng rộng rãi cho dữ liệu giải trình tự thông lượng cao.

Tải tệp FASTQ:

>>> from datasets import load_dataset
>>> dataset = load_dataset("fastq", data_files="reads.fq")

Trình tải trả về năm cột:

Việc đọc các cột đã phân tích không cần Biopython; loại trừ record bằng columns, hoặc dùng dataset.cast_column("record", BioSequence(decode=False)) (nhập từ datasets) để truy cập bộ nhớ lưu trữ {"bytes": ..., "path": None} của nó mà không giải mã.

Chỉ tải các cột cụ thể:

>>> dataset = load_dataset("fastq", data_files="reads.fq", columns=["sequence", "quality"])

Các tệp nén (.fq.gz, .fastq.gz, .fq.bz2, .fq.xz) được tự động phát hiện và giải nén.

FASTA

FASTA là định dạng dựa trên văn bản để biểu diễn trình tự nucleotide (DNA/RNA) hoặc trình tự peptide (protein), được sử dụng rộng rãi trong tin sinh học.

Để tải một tệp FASTA:

>>> from datasets import load_dataset
>>> dataset = load_dataset("fasta", data_files="sequences.fasta")

Điều này trả về một tập dữ liệu với các cột sau:

• id: Định danh chuỗi (từ đầu tiên sau >)
• description: Dòng mô tả đầy đủ (mọi thứ sau id)
• sequence: Trình tự sinh học (DNA/RNA/đạm)
• record: Một BioSequence với format="fasta" lưu trữ các byte gốc của từng bản ghi, được giải mã thành SeqRecord của Biopython khi được truy cập.

Việc đọc các cột đã phân tích không cần Biopython; loại trừ record bằng columns, hoặc dùng dataset.cast_column("record", BioSequence(decode=False)) (nhập từ datasets) để truy cập bộ nhớ lưu trữ {"bytes": ..., "path": None} của nó mà không giải mã.

Bạn cũng có thể chỉ tải các cột cụ thể:

>>> dataset = load_dataset("fasta", data_files="sequences.fa", columns=["id", "sequence"])

Các tệp FASTA với nhiều phần mở rộng khác nhau được hỗ trợ: .fa, .fasta, .fna (axit nucleic), .ffn (nucleotide của vùng gen), .faa (axit amin) và .frn (RNA không mã hóa). Các tệp nén (gzip, bzip2, xz) sẽ được phát hiện và giải nén tự động.

Tệp từ xa

Nếu bạn có các tệp từ xa, có thể được lưu dưới dạng csv, json, txt, parquet hoặc bất kỳ định dạng nào được hỗ trợ, hàm load_dataset() có thể tải chúng nếu bạn chỉ định đường dẫn từ xa của chúng:

• URL https:// cho các tệp trực tuyến công khai, ví dụ data_files=["https://rajpurkar.github.io/SQuAD-explorer/dataset/train-v2.0.json"]
• URL hf:// cho các tệp trong bất kỳ kho Datasets hoặc Storage Bucket nào trên Hugging Face, ví dụ data_files=["hf://datasets/karpathy/tinystories-gpt4-clean/tinystories_gpt4_clean.parquet"] hoặc data_files=["hf://buckets/julien-c/my-training-bucket/julien/affluence.csv"]

Xử lý đa tiến trình

Khi một tập dữ liệu được tạo từ nhiều tệp (mà chúng ta gọi là “shards”), có thể tăng tốc đáng kể bước tải xuống và chuẩn bị tập dữ liệu.

Bạn có thể chọn số lượng tiến trình muốn dùng để chuẩn bị một tập dữ liệu song song bằng cách sử dụng num_proc. Trong trường hợp này, mỗi tiến trình được giao một tập con các shard để chuẩn bị:

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)

Dữ liệu trong bộ nhớ

🤗 Datasets cũng cho phép bạn tạo một Dataset trực tiếp từ các cấu trúc dữ liệu trong bộ nhớ như từ điển Python và DataFrame Pandas.

Từ điển Python

Tải các từ điển Python bằng from_dict():

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

Danh sách các từ điển trong Python

Tải một danh sách các từ điển Python bằng from_list():

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

Trình tạo Python

Tạo một dataset từ một generator Python bằng from_generator():

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

Cách tiếp cận này hỗ trợ nạp dữ liệu lớn hơn bộ nhớ khả dụng.

Bạn cũng có thể định nghĩa một tập dữ liệu phân mảnh bằng cách truyền các danh sách vào 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

Tải các DataFrame Pandas bằng from_pandas():

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

Để biết thêm chi tiết, hãy xem hướng dẫn cách tải bộ dữ liệu bảng từ Pandas DataFrames.

Ngoại tuyến

Ngay cả khi không có kết nối internet, bạn vẫn có thể tải một dataset. Miễn là bạn đã tải xuống một dataset từ kho Hub trước đó, nó sẽ được lưu trong bộ nhớ đệm. Điều này có nghĩa là bạn có thể tải lại dataset từ bộ nhớ đệm và sử dụng nó ngoại tuyến.

Nếu bạn biết rằng mình sẽ không có quyền truy cập internet, bạn có thể chạy 🤗 Datasets ở chế độ ngoại tuyến hoàn toàn. Điều này giúp tiết kiệm thời gian vì thay vì chờ quá trình tải xuống của Dataset builder hết thời gian chờ, 🤗 Datasets sẽ tìm trực tiếp trong bộ nhớ đệm. Đặt biến môi trường HF_HUB_OFFLINE thành 1 để bật chế độ ngoại tuyến hoàn toàn.

Chia nhỏ

Bạn cũng có thể chỉ tải các phần cụ thể của một split. Có hai tùy chọn để cắt một split: sử dụng chuỗi hoặc API ReadInstruction. Chuỗi gọn gàng và dễ đọc hơn trong các trường hợp đơn giản, trong khi ReadInstruction dễ sử dụng hơn với các tham số cắt biến đổi.

Nối một phần train và một phần test bằng cách:

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

Chọn các hàng cụ thể của phần chia train:

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

Hoặc chọn một phần trăm của một split bằng cách:

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

Chọn một tổ hợp phần trăm từ mỗi tập chia:

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

Cuối cùng, bạn thậm chí có thể tạo ra các phần chia kiểm định chéo. Ví dụ bên dưới tạo ra các phần chia kiểm định chéo 10-fold. Mỗi tập dữ liệu kiểm định là một phần 10%, và tập dữ liệu huấn luyện chiếm phần bổ sung còn lại là 90%:

 
String API 
ReadInstruction
>>> 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)])

Cắt và làm tròn theo phần trăm

Hành vi mặc định là làm tròn các ranh giới đến số nguyên gần nhất đối với các bộ dữ liệu mà ranh giới lát cắt được yêu cầu không chia hết cho 100. Như minh họa bên dưới, một số lát cắt có thể chứa nhiều ví dụ hơn những lát cắt khác. Ví dụ, nếu phần chia train sau đây bao gồm 999 bản ghi, thì:

# 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%]")

Nếu bạn muốn các phần chia có kích thước bằng nhau, hãy dùng làm tròn pct1_dropremainder thay thế. Cách này coi các ranh giới phần trăm được chỉ định là bội số của 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)")

Việc làm tròn pct1_dropremainder có thể cắt bỏ các ví dụ cuối cùng trong bộ dữ liệu nếu số lượng ví dụ trong bộ dữ liệu của bạn không chia hết cho 100.

Xử lý sự cố

Đôi khi, bạn có thể nhận được kết quả không như mong đợi khi tải một bộ dữ liệu. Hai vấn đề phổ biến nhất mà bạn có thể gặp phải là tải thủ công một bộ dữ liệu và chỉ định các đặc trưng của bộ dữ liệu.

Chỉ định các tính năng

Khi bạn tạo một dataset từ các tệp cục bộ, các Features sẽ được suy luận tự động bởi Apache Arrow. Tuy nhiên, các đặc trưng của dataset có thể không luôn khớp với kỳ vọng của bạn, hoặc bạn có thể muốn tự định nghĩa các đặc trưng. Ví dụ dưới đây cho thấy cách bạn có thể thêm các nhãn tùy chỉnh bằng đặc trưng ClassLabel.

Bắt đầu bằng cách định nghĩa các nhãn của riêng bạn bằng lớp Features:

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

Tiếp theo, chỉ định tham số features trong load_dataset() với các đặc trưng bạn vừa tạo:

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

Bây giờ khi bạn xem các đặc trưng của tập dữ liệu, bạn có thể thấy nó sử dụng các nhãn tùy chỉnh mà bạn đã định nghĩa:

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