Processar grandes conjuntos de dados

Cada Job vem com uma quantidade fixa de disco local, definida pelo seu hardware flavor (a coluna Ephemeral Storage, também exibida por hf jobs hardware). Você não precisa caber um dataset inteiro nesse disco para trabalhar com ele: datasets e Storage Buckets podem ser lidos diretamente do Hub — em streaming, consultados ou montados —, de modo que um único Job pode processar dados muito maiores do que o seu disco. Esta página aborda as opções e quando recorrer a cada uma.

Qual abordagem?

• Cabe no disco → um simples load_dataset(...) funciona como está (ou apenas escolha uma versão maior — até 1 TB de disco efêmero).
• Iterar sobre linhas, processar ou treinar → stream it.
• Varreduras filtradas ou com colunas reduzidas → consulte-o diretamente sobre hf:// com Polars ou DuckDB.
• Ferramentas que esperam caminhos de arquivo locais → mount o repositório e leia-o de forma preguiçosa.
• Permanência dos resultados → escreva-os em um Storage Bucket para que sobrevivam ao Job.

Transmitir o conjunto de dados

A leitura em streaming consome exemplos do Hub conforme seu código os utiliza — sem download, sem cópia local e com escala para conjuntos de dados de múltiplos TB. As versões recentes tornaram isso até 100× mais eficiente, alcançando desempenho equivalente ao de SSDs locais ao treinar em muitos 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

Um dataset em streaming é um IterableDataset que suporta .filter(), .map(), .shuffle(buffer_size=...) e .batch() preguiçosos, e pode ser passado diretamente para um DataLoader do PyTorch ou para um Trainer para treinar com dados maiores que o disco. Consulte o Guia de streaming para a API completa e Exemplos e tutoriais para guias de treinamento de ponta a ponta em configurações de nó único ou distribuídas.

O streaming também funciona em configurações distribuídas, usando Spark:

import pyspark_huggingface

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

O dataframe Spark resultante é distribuído: cada worker faz streaming de seu próprio subconjunto de arquivos. Consulte a documentação do Spark para exemplos de leitura, gravação e filtragem eficiente de linhas e colunas.

Leia e filtre sobre hf://

Muitas bibliotecas de dados leem conjuntos de dados do Hub diretamente por meio de caminhos hf:// — Polars, DuckDB e pandas escaneiam Parquet do Hub nativamente, empurrando filtros e seleção de colunas para dentro do escaneamento, de modo que um único Job pode processar muito mais dados do que cabem na memória ou no disco. Esta consulta resume ~28 GB de Parquet em cerca de quatro minutos no sabor padrão de CPU:

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)

Scans como esse são limitados pela rede, não pela memória, e os motores diferem em como paralelizam agressivamente as leituras remotas, de modo que os tempos variam conforme a biblioteca. Duas consequências práticas: defina --timeout acima do padrão de 30 minutos para scans longos e divida o trabalho entre vários Jobs executados em paralelo para ganhar velocidade. Consulte Polars, DuckDB e pandas para exemplos por biblioteca, e Python data tools para ler buckets via hf:// (que passa por HfFileSystem).

Monte um conjunto de dados, modelo ou bucket

Monte um repositório ou bucket no Job como um caminho local com -v / --volume; os arquivos são obtidos sob demanda pela rede conforme seu código os lê, de modo que qualquer ferramenta que lê arquivos locais funciona normalmente:

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 é a opção natural quando os arquivos são consumidos por inteiro — pesos de modelo, arquivos de áudio ou imagem, arquivos compactados — ou quando uma ferramenta aceita apenas caminhos de arquivo. Para varreduras de Parquet com múltiplos arquivos grandes, consultar diretamente via hf:// é tipicamente várias vezes mais rápido do que varrer por meio de um mount.

Datasets e modelos são montados somente para leitura; buckets são de leitura e escrita, o que os torna um bom local para salvar resultados. Consulte Configuração para a sintaxe completa de -v e padrões de acesso a buckets para mais detalhes.

Arquivos lidos por meio de um mount são cacheados no disco efêmero do Job, portanto, ler de forma preguiçosa (um arquivo por vez) mantém a pegada pequena. Ao executar um script local com hf jobs uv run, o diretório do script é montado em /data, então monte seus dados em outro local (por exemplo, /mnt/data).

Salvar resultados

O disco efêmero não sobrevive ao Job, então escreva tudo o que deseja manter em um Storage Bucket montado para leitura e escrita, ou envie para o Hub como um dataset. O DuckDB pode filtrar a origem via hf:// e escrever os correspondentes diretamente em um bucket montado em uma única consulta out-of-core, de modo que o resultado nunca precise caber na memória:

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

Arquivos gravados no caminho de montagem do bucket persistem após o término do Job. Para publicar um dataset processado, use Dataset.push_to_hub.

Exemplo prático: consultar o Common Crawl sem baixá-lo

O Common Crawl espelha seu arquivo no bucket commoncrawl/commoncrawl — centenas de TB. Transmita um shard WET (texto puro) diretamente do hf://, analise-o e consulte-o com DuckDB; apenas alguns MB transitam, pois o gzip é lido sequencialmente e interrompido precocemente:

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

Execute com hf jobs uv run cc_wet.py — ele é concluído em cerca de um minuto no sabor de CPU padrão e imprime:

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

Veja também

• Stream · Conjuntos de dados em streaming: 100× mais eficientes
• Preços e hardware — disco efêmero por sabor · Configuração — volumes
• Buckets de armazenamento · padrões de acesso · integrações