Memproses Dataset Besar

Setiap Job dilengkapi dengan jumlah disk lokal tetap, yang ditentukan oleh hardware flavor-nya (kolom Ephemeral Storage, yang juga ditampilkan oleh hf jobs hardware). Anda tidak perlu memuat seluruh dataset ke disk tersebut untuk dapat bekerja dengannya: dataset dan Storage Buckets dapat dibaca langsung dari Hub — di-stream, dikueri, atau di-mount — sehingga satu Job dapat memproses data yang jauh lebih besar daripada kapasitas disknya. Halaman ini membahas opsi-opsi tersebut dan kapan sebaiknya menggunakan masing-masing.

Pendekatan mana?

• Muat di disk → load_dataset(...) biasa berfungsi apa adanya (atau cukup pilih varian yang lebih besar — hingga 1 TB disk sementara).
• Iterasi baris, pemrosesan atau pelatihan → stream
• Scan yang difilter atau dipangkas kolomnya → kueri secara langsung melalui hf:// dengan Polars atau DuckDB.
• Alat yang mengharapkan jalur file lokal → mount repo dan bacanya secara lazy.
• Menyimpan hasil → tulis ke Storage Bucket agar bertahan setelah Job selesai.

Stream dataset

Streaming membaca contoh dari Hub saat kode Anda mengonsumsinya — tanpa unduhan, tanpa salinan lokal, dan dapat diskalakan ke dataset multi-TB. Rilis terbaru membuatnya hingga 100× lebih efisien, mencapai kinerja setara dengan SSD lokal saat melatih di banyak worker:

from datasets import load_dataset

ds = load_dataset("HuggingFaceFW/fineweb-edu", "sample-10BT", split="train", streaming=True)
for example in ds.take(1000):
    ...  # streams in as you iterate, nothing hits disk

Dataset yang di-stream adalah IterableDataset yang mendukung .filter() yang lazy, .map(), .shuffle(buffer_size=...), dan .batch(), dan dapat langsung diteruskan ke DataLoader PyTorch atau Trainer untuk melatih pada data yang lebih besar dari disk. Lihat Panduan Stream untuk API lengkap, dan Contoh & Tutorial untuk panduan pelatihan end-to-end untuk setup single-node atau terdistribusi.

Streaming juga berfungsi dalam setup terdistribusi, menggunakan Spark:

import pyspark_huggingface

df = spark.read.format("huggingface").option("config", "sample-10BT").load("HuggingFaceFW/fineweb-edu")

Dataframe Spark yang dihasilkan bersifat terdistribusi: setiap worker melakukan streaming dari subset file miliknya sendiri. Lihat dokumentasi Spark untuk contoh membaca, menulis, dan memfilter baris serta kolom secara efisien.

Baca dan saring di atas hf://

Banyak pustaka data membaca dataset Hub langsung melalui jalur hf:// — Polars, DuckDB, dan pandas semuanya memindai Parquet Hub secara native, mendorong filter dan pemilihan kolom ke dalam proses pemindaian, sehingga satu Job dapat memproses jauh lebih banyak data daripada yang muat di memori atau di disk. Kueri ini merangkum sekitar 28 GB Parquet dalam waktu sekitar empat menit pada varian CPU default:

import polars as pl

agg = (
    pl.scan_parquet("hf://datasets/HuggingFaceFW/fineweb-edu/sample/10BT/*.parquet")
    .filter(pl.col("int_score") >= 4)
    .group_by("int_score")
    .agg(pl.len().alias("docs"), pl.col("token_count").sum().alias("tokens"))
    .sort("int_score")
    .collect()
)
print(agg)

Scan seperti ini dibatasi oleh jaringan, bukan memori, dan mesin berbeda dalam hal seberapa agresif mereka memparalelkan pembacaan jarak jauh, sehingga waktu eksekusi bervariasi antar pustaka. Dua konsekuensi praktis: atur --timeout di atas nilai default 30 menit untuk scan panjang, dan bagi pekerjaan ke beberapa Job yang berjalan paralel agar lebih cepat. Lihat Polars, DuckDB, dan pandas untuk contoh per pustaka, serta Python data tools untuk membaca buckets melalui hf:// (yang melewati HfFileSystem).

Pasang dataset, model, atau bucket

Pasang repositori atau bucket ke dalam Job sebagai jalur lokal dengan -v / --volume; file diambil secara malas melalui jaringan saat kode Anda membacanya, sehingga alat apa pun yang membaca file lokal akan berfungsi:

hf jobs uv run --flavor cpu-upgrade \
  -v hf://datasets/HuggingFaceFW/fineweb-edu:/mnt/data \
  process.py

# /// script
# dependencies = ["polars"]
# ///
# process.py — the mounted repo is just a directory of files
from pathlib import Path

import polars as pl

for path in Path("/mnt/data/sample/10BT").glob("*.parquet"):
    shard = pl.read_parquet(path)
    ...  # process one shard at a time, write results out

Mounting adalah pilihan yang paling tepat ketika file dikonsumsi secara utuh — bobot model, file audio atau gambar, arsip — atau ketika sebuah alat hanya menerima jalur file. Untuk pemindaian Parquet multi-file berukuran besar, melakukan kueri langsung melalui hf:// biasanya beberapa kali lebih cepat daripada memindai melalui mount.

Dataset dan model dimount hanya-baca; bucket bersifat baca-tulis, sehingga menjadi tempat yang baik untuk menyimpan hasil. Lihat Konfigurasi untuk sintaks lengkap -v dan pola akses bucket untuk detailnya.

File yang dibaca melalui mount di-cache pada disk sementara Job, sehingga membaca secara lazy (satu file pada satu waktu) menjaga footprint tetap kecil. Saat menjalankan skrip lokal dengan hf jobs uv run, direktori skrip di-mount di /data, jadi mount data Anda di tempat lain (mis. /mnt/data).

Simpan hasil

Disk ephemeral tidak bertahan setelah Job selesai, jadi tulis apa pun yang ingin Anda simpan ke Storage Bucket yang dipasang dengan mode baca-tulis, atau dorongnya ke Hub sebagai dataset. DuckDB dapat memfilter sumber melalui hf:// dan menulis hasil yang cocok langsung ke bucket yang dipasang dalam satu query out-of-core, sehingga hasil tidak perlu muat di memori:

hf jobs uv run --flavor cpu-upgrade --timeout 1h \
  -v hf://buckets/username/my-output:/mnt/out \
  filter.py

# /// script
# dependencies = ["duckdb"]
# ///
# filter.py — scan ~28 GB of Parquet, keep only the matching rows
import duckdb

duckdb.sql(
    """
    COPY (
        SELECT text, url, token_count
        FROM 'hf://datasets/HuggingFaceFW/fineweb-edu/sample/10BT/*.parquet'
        WHERE int_score >= 4 AND token_count >= 4000
    ) TO '/mnt/out/result.parquet' (FORMAT parquet)
    """
)

File yang ditulis di bawah jalur mount bucket tetap tersimpan setelah Job berakhir. Untuk menerbitkan dataset yang telah diproses, gunakan Dataset.push_to_hub.

Contoh penerapan: kueri Common Crawl tanpa mengunduhnya

Common Crawl mencerminkan arsipnya ke bucket commoncrawl/commoncrawl — ratusan TB. Alirkan satu shard WET (teks polos) langsung dari hf://, analisis, dan kueri dengan DuckDB; hanya beberapa MB yang bertransit karena gzip dibaca secara berurutan dan dihentikan lebih awal:

# /// script
# requires-python = ">=3.11"
# dependencies = ["huggingface_hub>=1.9", "fastwarc>=0.15", "duckdb>=1.0"]
# ///
import duckdb
from fastwarc.warc import ArchiveIterator, WarcRecordType
from huggingface_hub import hffs

WET = (
    "buckets/commoncrawl/commoncrawl/crawl-data/CC-MAIN-2026-17/"
    "segments/1775805908305.14/wet/"
    "CC-MAIN-20260410081153-20260410111153-00000.warc.wet.gz"
)

rows = []
with hffs.open(WET, "rb") as f:
    for rec in ArchiveIterator(f, record_types=WarcRecordType.conversion):
        lang = (rec.headers.get("WARC-Identified-Content-Language", "") or "und").split(",")[0]
        rows.append((rec.headers.get("WARC-Target-URI", ""), lang, len(rec.reader.read())))
        if len(rows) >= 5000:
            break

con = duckdb.connect()
con.execute("CREATE TABLE wet(url VARCHAR, lang VARCHAR, n_chars BIGINT)")
con.executemany("INSERT INTO wet VALUES (?,?,?)", rows)
con.sql("SELECT lang, count(*) AS docs FROM wet GROUP BY lang ORDER BY docs DESC LIMIT 10").show()

Jalankan dengan hf jobs uv run cc_wet.py — selesai dalam sekitar satu menit pada varian CPU default dan mencetak:

┌─────────┬───────┐
│  lang   │ docs  │
│ varchar │ int64 │
├─────────┼───────┤
│ eng     │  1974 │
│ zho     │   586 │
│ rus     │   434 │
│ jpn     │   244 │
│ …       │    …  │
└─────────┴───────┘

Lihat juga

• Stream · Dataset streaming: 100× lebih efisien
• Harga & perangkat keras — disk sementara per varian · Konfigurasi — volume
• Storage Buckets · pola akses · integrasi