Procesar conjuntos de datos grandes

Cada Job viene con una cantidad fija de disco local, definida por su hardware flavor (la columna Ephemeral Storage, también mostrada por hf jobs hardware). No es necesario que un conjunto de datos completo quepa en ese disco para trabajar con él: los datasets y los Storage Buckets se pueden leer directamente desde el Hub, ya sea mediante streaming, consultas o montaje, de modo que un solo Job puede procesar datos mucho más grandes que su disco. Esta página cubre las opciones disponibles y cuándo conviene utilizar cada una.

¿Qué enfoque?

• Cabe en el disco → un simple load_dataset(...) funciona tal cual (o simplemente elige una versión más grande, hasta 1 TB de disco efímero).
• Iterar sobre filas, procesar o entrenar → stream it.
• Escaneos filtrados o con columnas recortadas → consúltalo directamente sobre hf:// con Polars o DuckDB.
• Las herramientas que esperan rutas de archivos locales → montar el repositorio y leerlo de forma perezosa.
• Guardar los resultados → escríbelos en un Storage Bucket para que sobrevivan al Job.

Transmitir el conjunto de datos

Las lecturas en streaming obtienen ejemplos del Hub a medida que tu código los consume: sin descargas, sin copia local y con capacidad para escalar a conjuntos de datos de varios TB. Las versiones recientes lo hicieron hasta 100 veces más eficiente, alcanzando un rendimiento comparable al de los SSD locales al entrenar con muchos workers:

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

Un dataset en streaming es un IterableDataset que admite .filter(), .map(), .shuffle(buffer_size=...) y .batch() de forma perezosa, y puede pasarse directamente a un DataLoader de PyTorch o a un Trainer para entrenar con datos más grandes que el disco. Consulte la Guía de streaming para la API completa y Ejemplos y tutoriales para recorridos de entrenamiento de principio a fin en configuraciones de un solo nodo o distribuidas.

El streaming también funciona en configuraciones distribuidas, usando Spark:

import pyspark_huggingface

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

El dataframe de Spark resultante está distribuido: cada worker transmite desde su propio subconjunto de archivos. Consulte la documentación de Spark para ejemplos de lectura, escritura y filtrado eficiente de filas y columnas.

Leer y filtrar sobre hf://

Muchas bibliotecas de datos leen conjuntos de datos de Hub directamente a través de rutas hf://: Polars, DuckDB y pandas escanean Parquet de Hub de forma nativa, delegando los filtros y la selección de columnas en el escaneo, de modo que un solo Job puede procesar mucho más datos de los que caben en memoria o en disco. Esta consulta resume unos 28 GB de Parquet en aproximadamente cuatro minutos en la variante de CPU predeterminada:

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)

Escaneos como este están limitados por la red y no por la memoria, y los motores difieren en cómo paralelizan de forma agresiva las lecturas remotas, por lo que los tiempos varían según la biblioteca. Dos consecuencias prácticas: configure --timeout por encima del valor predeterminado de 30 minutos para escaneos largos, y divida el trabajo entre varios Jobs que se ejecutan en paralelo para ir más rápido. Consulte Polars, DuckDB y pandas para ejemplos por biblioteca, y Python data tools para leer buckets a través de hf:// (que pasa por HfFileSystem).

Montar un conjunto de datos, un modelo o un bucket

Monta un repositorio o cubo en el Job como una ruta local con -v / --volume; los archivos se obtienen de forma perezosa a través de la red a medida que tu código los lee, por lo que cualquier herramienta que lea archivos locales funciona sin problemas:

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

Montar es la opción natural cuando los archivos se consumen completos: pesos de modelos, archivos de audio o imagen, archivos comprimidos, o cuando una herramienta solo acepta rutas de archivo. Para escaneos de Parquet con múltiples archivos de gran tamaño, consultar directamente sobre hf:// suele ser varias veces más rápido que escanear a través de un montaje.

Los conjuntos de datos y los modelos se montan en solo lectura; los buckets son de lectura y escritura, lo que los convierte en un buen lugar para guardar resultados. Consulte Configuración para la sintaxis completa de -v y patrones de acceso a buckets para más detalles.

Los archivos leídos a través de un montaje se almacenan en caché en el disco efímero del Job, por lo que leerlos de forma perezosa (un archivo a la vez) mantiene la huella pequeña. Al ejecutar un script local con hf jobs uv run, el directorio del script se monta en /data, por lo que debe montar sus datos en otra ubicación (p. ej. /mnt/data).

Guardar resultados

El disco efímero no sobrevive al Job, por lo que escriba en un Storage Bucket montado en modo lectura-escritura todo lo que desee conservar, o publíquelo en el Hub como un dataset. DuckDB puede filtrar la fuente sobre hf:// y escribir las coincidencias directamente en un bucket montado en una sola consulta out-of-core, de modo que el resultado nunca tiene que caber en memoria:

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

Los archivos escritos en la ruta de montaje del bucket persisten después de que el Job termina. Para publicar un dataset procesado en su lugar, use Dataset.push_to_hub.

Ejemplo práctico: consultar Common Crawl sin descargarlo

Common Crawl replica su archivo en el bucket commoncrawl/commoncrawl — cientos de TB. Transmite un shard WET (texto plano) directamente desde hf://, analízalo y consulta con DuckDB; solo unos pocos MB transitan porque el gzip se lee de forma secuencial y se detiene anticipadamente:

# /// 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()

Ejecútalo con hf jobs uv run cc_wet.py — se completa en aproximadamente un minuto en el sabor de CPU predeterminado e imprime:

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

Véase también

• Stream · Conjuntos de datos en streaming: 100 veces más eficientes
• Precios y hardware — disco efímero por sabor · Configuración — volúmenes
• Buckets de almacenamiento · patrones de acceso · integraciones