Hugging Face Datasets: Riferimento per gli sviluppatori

Un dataset di Hugging Face è una raccolta di dati strutturata e versionata, memorizzata su Hugging Face Hub e utilizzata tramite la libreria Python datasets . Ogni dataset espone una o piùsuddivisioni (tipicamente train, validation e test), uno schema tipizzato che descrive ogni colonna e metadati relativi a licenza, categoria di compito ed etichette linguistiche. La libreria gestisce automaticamente il download, la cache e la conversione del formato, quindi quasi mai devi interagire direttamente con i file grezzi.caratteristiche schema che descrive ogni colonna e metadati che coprono licenza, categoria di compito ed etichette linguistiche. La libreria si occupa del download, della cache e della conversione del formato, quindi quasi mai devi gestire direttamente i file grezzi.

Finding Datasets on the Hub

L’interfaccia principale per la ricerca è huggingface.co/datasets. I filtri disponibili nell’interfaccia utente sono:

• Attività — classificazione del testo, risposta a domande, segmentazione di immagini, traduzione, riassunto e altro ancora
• Lingua — codici ISO 639-1 (en, zh, fr, de, …)
• Licenza — Apache 2.0, MIT, CC-BY, CC0, OpenRAIL, ecc.
• Categoria di dimensione — meno di 1.000 righe fino a oltre 1 miliardo di righe
• Modalità — testo, immagine, audio, video, dati tabellari, multimodali

Puoi anche effettuare ricerche a livello programmatico tramite il client Python dell’Hub:

from huggingface_hub import list_datasets

results = list_datasets(filter='task_categories:text-classification', limit=20)
for ds in results:
    print(ds.id, ds.downloads)

L’API REST del Datasets Server espone un endpoint /valid che elenca tutti i dataset dotati di esportazioni precalcolate in formato Parquet, consentendo anteprime rapide e campionamenti di righe senza dover scaricare l’intero dataset.

Installazione

Ildatasets La libreria è compatibile con Python 3.8+ ed è indipendente dalla piattaforma.

pip install datasets

Per il supporto a immagini e audio, installa gli extra appropriati:

pip install datasets[vision] # Pillow
pip install datasets         # librosa, soundfile

Per autenticarti ai dataset privati o per pubblicare dati sull’Hub:

pip install huggingface_hub
huggingface-cli login          # richiede il token di accesso a HF

Il token viene salvato in ~/.cache/huggingface/token su macOS/Linux oppure in %USERPROFILE%.cache/huggingface/token su Windows. In alternativa, puoi impostare direttamente la HF_TOKEN variabile d’ambiente.

Caricamento di un dataset

Il punto di ingresso principale è load_dataset(). Se non si specifica l’argomentosplit , la funzione restituisce un oggetto DatasetDict che contiene tutte le suddivisioni disponibili:

from datasets import load_dataset

ds = load_dataset('stanfordnlp/imdb')
print(ds)
# DatasetDict({
#     train: Dataset({features: ['text', 'label'], num_rows: 25000})
#     test:  Dataset({features: ['text', 'label'], num_rows: 25000})
# })

train = ds['train']
print(train.features)
# {'text': Value(dtype='string'), 'label': ClassLabel(names=['neg', 'pos'])}

print(train[0]['text'][:120])

Caricamento di una singola suddivisione

train = load_dataset('stanfordnlp/imdb', split='train')
# Restituisce un Dataset direttamente, non un DatasetDict

Caricamento di una configurazione denominata

Molti dataset definiscono configurazioni denominate per varianti linguistiche, sottoinsiemi di dominio o versioni dello schema. Passa il nome della configurazione come secondo argomento posizionale:

ds = load_dataset('Helsinki-NLP/opus_books', 'en-fr')

Per elencare tutte le configurazioni disponibili per un dataset prima del caricamento:

from datasets import get_dataset_config_names
print(get_dataset_config_names('Helsinki-NLP/opus_books'))

Caricamento da file locali

Passa invece di un ID dataset Hub un nome di formato e un percorso file. I formati supportati includono CSV, JSON/JSONL, Parquet, Arrow, testo semplice e le convenzioni ImageFolder/AudioFolder.

ds = load_dataset('csv', data_files='my_data.csv')
ds = load_dataset('json', data_files={'train': 'train.jsonl', 'test': 'test.jsonl'})
ds = load_dataset('imagefolder', data_dir='./photos/')

Struttura di un dataset: suddivisioni e caratteristiche

Verifica quali suddivisioni (split) possiede un dataset prima del caricamento:

from datasets import get_dataset_split_names
print(get_dataset_split_names('stanfordnlp/imdb'))
# ['train', 'test', 'unsupervised']

Ilcaratteristiche Il dizionario mappa i nomi delle colonne a descrittori tipizzati. Tipi di feature comuni:

Tipo di feature	Esempio	Note
Valore	Value(dtype='string')	Scalare — stringa, int32, float32, bool, ecc.
ClassLabel	ClassLabel(names=['neg','pos'])	Memorizzato come intero; decodificato nel nome all’accesso
Sequence	Sequence(Value('int32'))	Lista di lunghezza variabile di un valore tipizzato
Image	Image()	Immagine PIL; memorizzata come byte, decodificata in modo lazy
Audio	Audio(sampling_rate=16000)	Dizionario con chiavi array e sampling_rate chiavi
Translation	Translation(languages=['en','fr'])	Dizionario indicizzato dal codice linguistico

Streaming di dataset di grandi dimensioni

Per dataset troppo grandi da scaricare — Common Crawl, The Pile, LAION-5B — passa streaming=True. I dati vengono recuperati e decodificati al volo senza occupare spazio sul disco:

ds = load_dataset('allenai/c4', 'en', split='train', streaming=True)

for example in ds.take(1000):
    print(example['text'][:80])

Il caricamento in streaming restituisce unIterableDataset anziché un Dataset. Supporta.map(), .filter(), .shuffle(buffer_size=N), e .take(N), ma non l’indicizzazione casuale né len(). Per ottenere una porzione fissa senza caricare in streaming l’intero dataset:

ds = load_dataset('allenai/c4', 'en', split='train[:50000]')

La suddivisione tramite slicing accetta conteggi assoluti di righe ([:50000]), percentuali ([:10%]) e intervalli con passo ([10%:20%]).

Filtraggio ed elaborazione

Tutte le operazioni vengono eseguite in Apache Arrow e utilizzano il multiprocessing per impostazione predefinita. Il risultato viene memorizzato nella cache su disco; rieseguire la stessa .map() sugli stessi dati restituisce immediatamente la cache.

# Filtra le righe
short = train.filter(lambda x: len(x['text']) < 500)

# Map in batch — molto più veloce per la tokenizzazione
def tokenize(batch):
    return tokenizer(batch['text'], truncation=True, padding='max_length')

tokenized = train.map(tokenize, batched=True, batch_size=256, num_proc=4)

# Operazioni sulle colonne
tokenized = tokenized.remove_columns(['text'])
ds = ds.rename_column('label', 'labels')

# Mescola e seleziona
ds = ds.shuffle(seed=42).select(range(10000))

Conversione in altri formati

Formato di destinazione	Metodo
DataFrame Pandas	ds.to_pandas()
Dataset PyTorch	ds.with_format('torch')
Dataset TensorFlow	ds.to_tf_dataset(columns=[...], batch_size=32)
Array NumPy	ds.with_format('numpy')
File Parquet	ds.to_parquet('output.parquet')
JSON / JSONL	ds.to_json('output.jsonl')
CSV	ds.to_csv('output.csv')

Pubblicazione del proprio dataset sull’Hub

Dopo aver eseguito huggingface-cli login, puoi inviare qualsiasiDataset o DatasetDict oggetto direttamente:

from datasets import Dataset, DatasetDict
import pandas as pd

df = pd.read_csv('my_data.csv')
ds = Dataset.from_pandas(df)

ds.push_to_hub('your-username/my-dataset', private=False)

Per caricare contemporaneamente le partizioni train e test:

split = ds.train_test_split(test_size=0.1)
DatasetDict({'train': split['train'], 'test': split['test']}).push_to_hub('your-username/my-dataset')

L’Hub memorizza i dataset come file Parquet suddivisi in shard e genera automaticamente un visualizzatore di anteprima per il dataset. Aggiungi una README.md (Scheda del dataset) con metadati YAML all’inizio del file per rendere il tuo dataset filtrabile per attività, lingua e licenza nell’interfaccia di ricerca dell’Hub.

Note sulla piattaforma

Percorsi della cache

Piattaforma	Percorso predefinito della cache	Variabile d’ambiente da sovrascrivere
macOS / Linux	~/.cache/huggingface/datasets/	HF_DATASETS_CACHE
Windows	%USERPROFILE%\.cache\huggingface\datasets	HF_DATASETS_CACHE

Windows

Su Windows viene utilizzato il metodo di avviospawn per il multiprocessing, il che richiede che il punto di ingresso dello script sia racchiuso in un blocco if __name__ == '__main__': Senza questo controllo,.map(num_proc=4) potrebbe bloccarsi o generare un errore RuntimeErrorSe stai eseguendo il codice in un notebook Jupyter, usa num_proc=1 oppure installa la libreriamultiprocess affiancato da datasets, che la libreria preferirà rispetto al modulo standard multiprocessing .

Spazio su disco

Dataset di grandi dimensioni (ad esempio Common Crawl, RedPajama, LAION) occupano centinaia di gigabyte quando vengono completamente memorizzati nella cache. Usa streaming=True per evitare i download. Per vedere cosa è presente nella tua cache, esegui python -c "from datasets import inspect_dataset; print(inspect_dataset.__doc__)" oppure esplora direttamente la directory della cache. I dataset memorizzati nella cache sono salvati come file Arrow organizzati per nome del dataset e hash; elimina manualmente le sottocartelle per liberare spazio.

Uso dei dataset per il fine-tuning e la valutazione

La pipeline standard per il fine-tuning è la seguente: caricare il dataset → tokenizzarlo con.map(batched=True) → impostare il formato su 'torch' → passarlo a un oggettoTrainer o a un ciclo di addestramento personalizzato. La classe transformers di Hugging Face accetta direttamente un oggetto Trainer come argomento per i parametri Dataset train_dataset e e eval_dataset .

Quando si valutano modelli su dataset di benchmark, i Classifica LLM fornisce punteggi su comuni insiemi di valutazione — un contesto utile quando si deve decidere quale dataset utilizzare per il proprio benchmark. Se stai valutando se eseguire un fine-tuning e ospitare autonomamente il modello oppure chiamare un'API, il self-hosting vs API break-even calculator può modellare il punto di pareggio dei costi in base al volume di richieste. Per i costi grezzi per token dell'API tra diversi provider, utilizza il Calcolatore costi API. E se prevedi di eseguire localmente un modello sottoposto a fine-tuning, la VRAM è il vincolo rigido — il Calcolatore VRAM stima i requisiti di memoria GPU in base alle dimensioni del modello e alla precisione della quantizzazione.

Frequently Asked Questions

Qual è la differenza tra un Dataset e un DatasetDict?

A Dataset è una singola suddivisione — una tabella con righe e colonne. Un DatasetDict è un contenitore simile a un dizionario che contiene più suddivisioni ed è il tipo restituito per impostazione predefinita da load_dataset() quando si omette l'argomento split . Accedi alle singole suddivisioni tramite la chiave corrispondente: ds['train'], ds['test'], ecc. Se passisplit='train', ottieni direttamente un oggetto Dataset semplice.

Come carico un dataset privato dall'Hub?

Autenticati innanzitutto con huggingface-cli login, oppure imposta la variabile d'ambiente HF_TOKEN con il tuo token di accesso. Quindi chiama load_dataset('org/private-dataset', token=True). Il blocco il flag come segreto nelle pipeline CI/CD e salta il passaggio interattivo di login. HF_TOKEN token=True

Perché load_dataset() richiede molto tempo alla prima chiamata?

La prima chiamata scarica i file di dati grezzi, li converte nel formato Apache Arrow e scrive la cache su disco. Per dataset di grandi dimensioni questo processo può richiedere minuti o più. Le chiamate successive sulla stessa macchina restituiscono quasi istantaneamente i file Arrow memorizzati nella cache. Se hai una connessione lenta o spazio su disco limitato, passa streaming=True per elaborare i dati al volo senza memorizzarli localmente nella cache.

Posso utilizzare i dataset Hugging Face senza connessione Internet?

Sì. Una volta che un dataset è stato memorizzato nella cache, imposta la variabile d'ambiente HF_DATASETS_OFFLINE=1 eload_dataset() leggerà esclusivamente dalla cache locale senza effettuare alcuna richiesta di rete. Questo è utile per server isolati (air-gapped), esecuzioni offline riproducibili o cluster HPC in cui i nodi worker non dispongono di accesso a Internet ma condividono un file system di rete contenente la directory della cache.

Quale formato di file utilizza l'Hub internamente?

I dataset memorizzati sull'Hub vengono serviti come file Apache Parquet, suddivisi in frammenti (shard). La libreria datasets scarica questi shard e li converte in file Apache Arrow (.arrow) per la cache locale. Puoi bypassare completamente la libreria e accedere direttamente ai frammenti Parquet tramite il browser dei file dell'Hub o utilizzando huggingface_hub.hf_hub_download().

Quanto grande può essere un dataset Hugging Face?

Non esiste un limite di dimensione imposto e sull'Hub sono presenti dataset di dimensioni superiori al terabyte (ad esempio le coppie immagine-testo LAION-5B o ampi snapshot di Common Crawl). Per dataset superiori a pochi gigabyte, l'Hub memorizza i dati come più shard Parquet anziché come un singolo file. Usa streaming=True nella libreria datasets per lavorare con questi dataset senza doverli scaricare integralmente, oppure scarica shard specifici tramite l'argomento data_files .