Hugging Face Datasets: Entwicklerreferenz

Ein Hugging-Face-Datensatz ist eine versionierte, strukturierte Datensammlung, die auf dem Hugging Face Hub gespeichert und über die Python-Bibliothek datasets verwendet wird. Jeder Datensatz stellt eine oder mehrereAufteilungen (typischerweise train, validation und test), ein typisiertesMerkmale Schema zur Beschreibung jeder Spalte sowie Metadaten zu Lizenz, Aufgabenkategorie und Sprachtags bereit. Die Bibliothek übernimmt das Herunterladen, Cachen und Formatkonvertieren, sodass Sie praktisch nie direkt mit Rohdateien arbeiten müssen.

Datensätze auf dem Hub finden

Die primäre Suchoberfläche ist huggingface.co/datasets. Im Benutzerinterface verfügbare Filter:

• Aufgabe — Textklassifikation, Fragebeantwortung, Bildsegmentierung, Übersetzung, Zusammenfassung und vieles mehr
• Sprache — ISO-639-1-Codes (en, zh, fr, de, …)
• Lizenz — Apache-2.0, MIT, CC-BY, CC0, OpenRAIL usw.
• Größenkategorie — unter 1.000 Zeilen bis über 1 Milliarde Zeilen
• Modality — Text, Bild, Audio, Video, tabellarische Daten, multimodale Daten

Sie können außerdem programmgesteuert über den Python-Client des Hubs suchen:

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)

Die REST-API des Datasets-Servers stellt einen Endpunkt /valid zur Verfügung, der alle Datensätze mit vorberechneten Parquet-Exporten auflistet und so schnelle Vorschauen und Zeilenstichproben ohne vollständiges Herunterladen des Datensatzes ermöglicht.

Installation

Derdatasets Die Bibliothek läuft unter Python 3.8+ und ist plattformunabhängig.

pip install datasets

Für Unterstützung von Bild- und Audioformaten installieren Sie die entsprechenden Zusatzpakete:

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

Um sich für private Datensätze zu authentifizieren oder Daten auf den Hub hochzuladen:

pip install huggingface_hub
huggingface-cli login          # Fordert Ihr HF-Zugriffstoken ab

Ihr Token wird unter macOS/Linux in ~/.cache/huggingface/token gespeichert, unter Windows in %USERPROFILE%\.cache\huggingface\token . Alternativ können Sie die HF_TOKEN Umgebungsvariable direkt setzen.

Einen Datensatz laden

Der primäre Einstiegspunkt ist load_dataset(). Ohne Angabe einessplit -Arguments gibt sie ein DatasetDict zurück, das alle verfügbaren Aufteilungen enthält:

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

Laden einer einzelnen Teilmenge

train = load_dataset('stanfordnlp/imdb', split='train')
# Gibt direkt ein Dataset zurück, kein DatasetDict

Laden einer benannten Konfiguration

Viele Datensätze definieren benannte Konfigurationen für Sprachvarianten, Domänen-Teilmengen oder Schemaversionen. Übergeben Sie den Konfigurationsnamen als zweites positionsbasiertes Argument:

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

Um alle verfügbaren Konfigurationen eines Datensatzes vor dem Laden aufzulisten:

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

Laden aus lokalen Dateien

Übergeben Sie statt einer Dataset-ID aus der Hugging Face Hub einen Formatnamen und einen Dateipfad. Unterstützte Formate umfassen CSV, JSON/JSONL, Parquet, Arrow, reine Textdateien sowie die Konventionen 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/')

Struktur eines Datensatzes: Aufteilungen und Features

Überprüfen Sie vor dem Laden, welche Teilmengen (Splits) ein Datensatz enthält:

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

DerMerkmale dict ordnet Spaltennamen typisierten Deskriptoren zu. Gängige Feature-Typen:

Große Datensätze streamen

Für Datensätze, die zu groß zum Herunterladen sind – z. B. Common Crawl, The Pile, LAION-5B – übergeben Sie streaming=True. Die Daten werden dynamisch abgerufen und decodiert, ohne Ihren Speicherplatz zu füllen:

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

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

Streaming gibt einIterableDataset statt eines Datasetzurück. Es unterstützt.map(), .filter(), .shuffle(buffer_size=N), und .take(N)– jedoch keine zufällige Indexierung oder len(). Um eine feste Teilmenge zu erhalten, ohne den gesamten Datensatz streamen zu müssen:

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

Die Teilmenge-Slicing-Syntax akzeptiert absolute Zeilenzahlen ([:50000])[:10%]), Prozentangaben ([10%:20%]).

Filtern und Verarbeiten

) und Schrittweitenbereiche ( .map() Alle Operationen werden in Apache Arrow ausgeführt und nutzen standardmäßig Mehrprozessverarbeitung (multiprocessing). Das Ergebnis wird auf der Festplatte zwischengespeichert; bei erneutem Ausführen desselben

auf denselben Daten wird sofort der Cache zurückgegeben.

# Zeilen filtern
short = train.filter(lambda x: len(x['text']) < 500)

# Batchweise Transformation – deutlich schneller für Tokenisierung
def tokenize(batch):
    return tokenizer(batch['text'], truncation=True, padding='max_length')

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

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

# Durchmischen und Auswahl
ds = ds.shuffle(seed=42).select(range(10000))

In andere Formate konvertieren

Eigene Datensätze auf den Hub hochladen

Nach Ausführung huggingface-cli login, können Sie jedesDataset oder DatasetDict Objekt direkt hochladen:

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)

So laden Sie Trainings- und Test-Splits gemeinsam hoch:

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

Der Hub speichert Datensätze als partitionierte Parquet-Dateien und generiert automatisch eine Vorschauansicht für den Datensatz. Fügen Sie eine README.md (Datensatzkarte) mit YAML-Front-Matter hinzu, um Ihren Datensatz im Hub-Suchinterface nach Aufgabe, Sprache und Lizenz filterbar zu machen.

Plattformhinweise

Cache-Pfade

Windows

Windows verwendet diespawn Startmethode für Multiprocessing, weshalb der Einstiegspunkt Ihres Skripts innerhalb einer if __name__ == '__main__': -Abfrage stehen muss. Andernfalls.map(num_proc=4) hängt entweder oder löst einen RuntimeErroraus. Wenn Sie in einem Jupyter-Notebook arbeiten, verwenden Sie entweder num_proc=1 oder installieren Siemultiprocess neben datasets, das die Bibliothek gegenüber dem Standard-Modul multiprocessing bevorzugt.

Festplattenspeicher

Große Datensätze (z. B. Common Crawl, RedPajama, LAION) beanspruchen beim vollständigen Cachen mehrere hundert Gigabyte. Verwenden Sie streaming=True , um Downloads zu vermeiden. Um anzuzeigen, was sich in Ihrem Cache befindet, führen Sie python -c "from datasets import inspect_dataset; print(inspect_dataset.__doc__)" aus oder durchsuchen Sie das Cache-Verzeichnis direkt. Gecachte Datensätze werden als Arrow-Dateien gespeichert, die nach Datensatzname und Hash organisiert sind; löschen Sie Unterordner manuell, um Speicherplatz freizugeben.

Verwendung von Datensätzen zum Feintuning und zur Bewertung

Die Standard-Feinabstimmungspipeline lautet: Datensatz laden → Tokenisierung mit.map(batched=True) → Format auf 'torch' festlegen → Übergabe an einenTrainer oder eine benutzerdefinierte Trainings-Schleife. Die Klasse transformers der Hugging Face-Bibliothek akzeptiert ein Trainer -Objekt direkt als Argument für Dataset train_dataset und und eval_dataset .

Bei der Bewertung von Modellen anhand von Benchmark-Datensätzen liefert die LLM-Leaderboard Bewertungsergebnisse für gängige Evaluations-Sets – eine nützliche Orientierungshilfe, wenn Sie entscheiden, welchen Datensatz Sie für Ihren eigenen Benchmark verwenden möchten. Wenn Sie abwägen, ob Sie ein Modell feinjustieren und selbst hosten oder stattdessen eine API aufrufen sollen, kann die Selbsthosting- versus-API-Kosten-Grenzwert-Rechner die Kostenbrechstelle in Abhängigkeit vom Anfragevolumen modellieren. Für die reinen pro-Token-API-Kosten verschiedener Anbieter nutzen Sie den API-Kostenrechner. Und falls Sie ein feinjustiertes Modell lokal ausführen möchten, stellt der VRAM die harte Beschränkung dar – der VRAM-Rechner schätzt den GPU-Speicherbedarf basierend auf Modellgröße und Quantisierungsgenauigkeit.

Häufig gestellte Fragen

Was ist der Unterschied zwischen einem Dataset und einem DatasetDict?

A Dataset ist eine einzelne Aufteilung – also eine einzige Tabelle mit Zeilen und Spalten. Ein DatasetDict ist ein wörterbuchähnlicher Container, der mehrere Aufteilungen enthält, und stellt den Standard-Rückgabetyp von load_dataset() dar, wenn Sie das Argument split weglassen. Greifen Sie auf einzelne Aufteilungen über den Schlüssel zu: ds['train'], ds['test'], usw. Wenn Siesplit='train'übergeben, erhalten Sie direkt ein einfaches Dataset .

Wie lade ich einen privaten Datensatz von der Hub?

Authentifizieren Sie sich zunächst mit huggingface-cli login, oder setzen Sie die Umgebungsvariable HF_TOKEN auf Ihr Zugriffstoken. Rufen Sie dann load_dataset('org/private-dataset', token=True). Der auf – das Flag weist die Bibliothek an, die zwischengespeicherte oder über die Umgebungsvariable bereitgestellte Anmeldeinformation zu verwenden. Für CI/CD-Pipelines legen Sie HF_TOKEN als Geheimnis fest und überspringen den interaktiven Anmeldevorgang.

Warum dauert der erste Aufruf von load_dataset() so lange?

Der erste Aufruf lädt die Rohdatendateien herunter, konvertiert sie ins Apache-Arrow-Format und schreibt den Cache auf die Festplatte. Bei großen Datensätzen kann dies mehrere Minuten oder länger dauern. Nachfolgende Aufrufe auf demselben Rechner liefern die zwischengespeicherten Arrow-Dateien nahezu sofort. Falls Sie über eine langsame Internetverbindung verfügen oder nur begrenzten Speicherplatz haben, übergeben Sie streaming=True , um die Daten ohne lokale Zwischenspeicherung dynamisch zu verarbeiten.

Kann ich Hugging-Face-Datensätze auch ohne Internetverbindung nutzen?

Ja. Sobald ein Datensatz zwischengespeichert ist, setzen Sie die Umgebungsvariable HF_DATASETS_OFFLINE=1 undload_dataset() – die Bibliothek liest dann ausschließlich aus dem lokalen Cache, ohne Netzwerkaufrufe durchzuführen. Dies ist nützlich für air-gapped-Server, reproduzierbare Offline-Läufe oder HPC-Cluster, bei denen Worker-Knoten keinen Internetzugang besitzen, aber ein gemeinsames Netzwerkspeichersystem mit dem Cache-Verzeichnis nutzen.

Welches Dateiformat verwendet die Hub intern?

Auf der Hub gespeicherte Datensätze werden als Apache-Parquet-Dateien bereitgestellt, die in Shards aufgeteilt sind. Die datasets Bibliothek lädt diese Shards herunter und konvertiert sie für die lokale Zwischenspeicherung ins Apache-Arrow-Format (.arrow). Sie können die Bibliothek vollständig umgehen und direkt über den Hub-Dateibrowser oder mithilfe von huggingface_hub.hf_hub_download().

auf die Parquet-Shards zugreifen.

Es gibt keine technisch erzwungene Größenbeschränkung, und es existieren mehrere Terabyte große Datensätze auf der Hub (z. B. LAION-5B Bild-Text-Paare oder umfangreiche Common-Crawl-Snapshots). Für Datensätze über wenigen Gigabyte speichert die Hub die Daten als mehrere Parquet-Shards statt als einzelne Datei. Nutzen Sie streaming=True in der datasets Bibliothek, um mit solchen Datensätzen zu arbeiten, ohne sie vollständig herunterzuladen, oder laden Sie gezielt bestimmte Shards über das data_files -Argument herunter.