Interagieren mit dem Hub über die Filesystem API

Zusätzlich zur HfApi bietet die huggingface_hub Bibliothek HfFileSystem, eine pythonische, fsspec-kompatible Dateischnittstelle zum Hugging Face Hub. Das HfFileSystem basiert auf der HfApi und bietet typische Dateisystemoperationen wie cp, mv, ls, du, glob, get_file, und put_file.

Verwendung

>>> from huggingface_hub import HfFileSystem
>>> fs = HfFileSystem()

>>> # Alle Dateien in einem Verzeichnis auflisten
>>> fs.ls("datasets/my-username/my-dataset-repo/data", detail=False)
['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv']

>>> # Alle ".csv"-Dateien in einem Repo auflisten
>>> fs.glob("datasets/my-username/my-dataset-repo/**.csv")
['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv']

>>> # Eine entfernte Datei lesen
>>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f:
...     train_data = f.readlines()

>>> # Den Inhalt einer entfernten Datei als Zeichenkette / String lesen
>>> train_data = fs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev")

>>> # Eine entfernte Datei schreiben
>>> with fs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f:
...     f.write("text,label")
...     f.write("Fantastic movie!,good")

Das optionale Argument revision kann übergeben werden, um eine Operation von einem spezifischen Commit auszuführen, wie z.B. einem Branch, Tag-Namen oder einem Commit-Hash.

Anders als bei Pythons eingebautem open, ist der Standardmodus von fsspec’s open binär, "rb". Das bedeutet, dass Sie den Modus explizit auf "r" zum Lesen und "w" zum Schreiben im Textmodus setzen müssen. Das Anhängen an eine Datei (Modi "a" und "ab") wird noch nicht unterstützt.

Integrationen

Das HfFileSystem kann mit jeder Bibliothek verwendet werden, die fsspec integriert, vorausgesetzt die URL folgt dem Schema:

hf://[<repo_type_prefix>]<repo_id>[@<revision>]/<pfad/im/repo>

Der repo_type_prefix ist datasets/ für Datensätze, spaces/ für Spaces, und Modelle benötigen kein Präfix in der URL.

Einige interessante Integrationen, bei denen HfFileSystem die Interaktion mit dem Hub vereinfacht, sind unten aufgeführt:

• Lesen/Schreiben eines Pandas DataFrame aus/in ein Hub-Repository:

  Copied

  >>> import pandas as pd
  
  >>> # Eine entfernte CSV-Datei in einen DataFrame lesen
  >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv")
  
  >>> # Einen DataFrame in eine entfernte CSV-Datei schreiben
  >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv")

  Der gleiche Arbeitsablauf kann auch für Dask und Polars verwendet werden.

• Abfrage von (entfernten) Hub-Dateien mit DuckDB:

  Copied

  >>> from huggingface_hub import HfFileSystem
  >>> import duckdb
  
  >>> fs = HfFileSystem()
  >>> duckdb.register_filesystem(fs)
  >>> # Eine entfernte Datei abfragen und das Ergebnis als DataFrame zurückbekommen
  >>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet"
  >>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df()

• Verwendung des Hub als Array-Speicher mit Zarr:

  Copied

  >>> import numpy as np
  >>> import zarr
  
  >>> embeddings = np.random.randn(50000, 1000).astype("float32")
  
  >>> # Ein Array in ein Repo schreiben
  >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w") as root:
  ...    foo = root.create_group("embeddings")
  ...    foobar = foo.zeros('experiment_0', shape=(50000, 1000), chunks=(10000, 1000), dtype='f4')
  ...    foobar[:] = embeddings
  
  >>> # Ein Array aus einem Repo lesen
  >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root:
  ...    first_row = root["embeddings/experiment_0"][0]

Authentifizierung

In vielen Fällen müssen Sie mit einem Hugging Face-Konto angemeldet sein, um mit dem Hub zu interagieren. Lesen Sie den Login-Abschnitt der Dokumentation, um mehr über Authentifizierungsmethoden auf dem Hub zu erfahren.

Es ist auch möglich, sich programmatisch anzumelden, indem Sie Ihr token als Argument an HfFileSystem übergeben:

>>> from huggingface_hub import HfFileSystem
>>> fs = HfFileSystem(token=token)

Wenn Sie sich auf diese Weise anmelden, seien Sie vorsichtig, das Token nicht versehentlich zu veröffentlichen, wenn Sie Ihren Quellcode teilen!