Interactuar con el Hub a través de la API de Filesystem

Además de HfApi, la biblioteca huggingface_hub ofrece HfFileSystem, una interfaz de archivos compatible con fsspec y de estilo python para el Hugging Face Hub. HfFileSystem se basa en HfApi y ofrece operaciones típicas de sistema de archivos como cp, mv, ls, du, glob, get_file y put_file.

HfFileSystem ofrece compatibilidad con fsspec, lo cual es útil para bibliotecas que la requieren (por ejemplo, para leer conjuntos de datos y cubos de Hugging Face directamente con pandas). Sin embargo, introduce un sobrecoste adicional debido a esta capa de compatibilidad. Para un mejor rendimiento y fiabilidad, se recomienda utilizar los métodos de HfApi cuando sea posible.

Uso

>>> from huggingface_hub import hffs

>>> # List all files in a dataset directory
>>> hffs.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']

>>> # List all files in a bucket directory
>>> hffs.ls("buckets/my-username/my-bucket/experiment-data", detail=False)
['bucket/my-username/my-bucket/data/train-0000.parquet', 'bucket/my-username/my-bucket/data/train-0001.parquet', ...]

>>> # List all ".csv" files in a dataset repository
>>> hffs.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']

>>> # Read a remote file
>>> with hffs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f:
...     train_data = f.readlines()

>>> # Read the content of a remote file as a string
>>> train_data = hffs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev")

>>> # Write a remote file
>>> with hffs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f:
...     f.write("text,label")
...     f.write("Fantastic movie!,good")

El argumento opcional revision se puede pasar para ejecutar una operación desde un commit específico, como una rama, una etiqueta o un hash de commit. Tenga en cuenta que revision no es compatible con Buckets.

A diferencia de la función open integrada de Python, la función open de fsspec usa el modo binario "rb" de forma predeterminada. Esto significa que debes establecer explícitamente el modo como "r" para leer y "w" para escribir en modo de texto. La adición de contenido a un archivo (modos "a" y "ab") aún no se admite.

Listado de repositorios grandes

Las operaciones que listan archivos de forma recursiva, como find y glob, necesitan obtener todo el contenido del repositorio. El Hub devuelve esas entradas página por página, y una página solo se puede solicitar una vez que se ha recibido la anterior: listar un repositorio que contiene 800k archivos requiere ~800 solicitudes secuenciales, y por lo tanto unos 30 minutos.

Para evitarlo, HfFileSystem lista los repositorios grandes directorio por directorio, en paralelo:

>>> from huggingface_hub import hffs

>>> # Takes ~30s on a repository holding 800k files
>>> files = hffs.glob("datasets/allenai/objaverse/**/*.glb", maxdepth=3)

El número de solicitudes concurrentes se controla mediante el argumento max_workers de HfFileSystem. Su valor predeterminado es 16 y se puede establecer en 1 para deshabilitar las listados paralelos. Tenga en cuenta que pasar un maxdepth también acelera significativamente los listados, ya que el Hub solo devuelve las entradas que se solicitan realmente.

Mantener las listas actualizadas

Los directorios se listan una vez y su contenido se almacena en caché, por lo que un directorio que otra persona acaba de modificar no se detecta automáticamente. HfFileSystem.invalidate_cache() elimina las listas en caché, ya sea para una ruta (y sus padres) o en todas partes cuando se llama sin argumento:

>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # listing is cached
>>> # ... another process uploads a file to the bucket ...
>>> hffs.invalidate_cache("buckets/my-username/my-bucket/data")
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # listed again
['buckets/my-username/my-bucket/data/train.csv', 'buckets/my-username/my-bucket/data/new-file.csv']

Para los buckets, huggingface_hub puede hacerlo por ti: el Hub transmite los cambios de archivos de un bucket a medida que ocurren y HfFileSystem elimina las listas afectadas por un cambio en cuanto este llega. Actívalo con live_follow=True:

>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(live_follow=True)
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # starts following that bucket
>>> # ... another process uploads a file to the bucket ...
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # refreshed as changes arrive
['buckets/my-username/my-bucket/data/train.csv', 'buckets/my-username/my-bucket/data/new-file.csv']

También se puede pasar a través de fsspec, con fsspec.filesystem("hf", live_follow=True) o a través del argumento storage_options de las bibliotecas que lo acepten (pandas, arrow, …).

Algunas cosas que debes saber al respecto:

• Solo cubos. Los repositorios de modelos, conjuntos de datos y espacios son repositorios git y el Hub no transmite sus cambios: pasa refresh=True a HfFileSystem.ls() (o usa HfApi.list_repo_tree()) para ver un nuevo commit.
• Only listings and the metadata they carry are refreshed. Reading a file always requests its content from the Hub, so live following only affects what ls, info, exists, glob, … report.
• El seguimiento comienza en cuanto se lista un bucket y se mantiene abierta una conexión de fondo por cada bucket seguido, compartida por todas las instancias de HfFileSystem. Por eso la opción es opt-in.

Integraciones

El HfFileSystem se puede usar con cualquier biblioteca que integre fsspec, siempre que la URL siga el esquema:

hf://[<repo_type_prefix>]<repo_id>[@<revision>]/<path/in/repo>

El repo_type_prefix es datasets/ para datasets, spaces/ para Spaces, y los modelos no necesitan un prefijo en la URL.

Además de los repositorios, HfFileSystem también admite los Buckets de Hugging Face, que son un almacenamiento de objetos similar a S3 (consulte esta guía para más detalles):

hf://buckets/<bucket_id>/<path/in/bucket>

A continuación se enumeran algunas integraciones interesantes en las que HfFileSystem simplifica la interacción con el Hub:

• Lectura/escritura de un DataFrame de Pandas desde/hacia un repositorio de Hub:

  Copiado

  >>> import pandas as pd
  
  >>> # Read a remote CSV file into a dataframe
  >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv")
  >>> df = pd.read_csv("hf://buckets/my-username/my-bucket/train.csv")
  
  >>> # Write a dataframe to a remote CSV file
  >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv")
  >>> df.to_csv("hf://buckets/my-username/my-bucket/test.csv")

El mismo flujo de trabajo también se puede utilizar para DataFrames de Dask y Polars.

• Consultar archivos (remotos) del Hub con DuckDB:

  Copiado

  >>> from huggingface_hub import HfFileSystem
  >>> import duckdb
  
  >>> fs = HfFileSystem()
  >>> duckdb.register_filesystem(fs)
  >>> # Query a remote file and get the result back as a dataframe
  >>> 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()

• Usar el Hub como almacén de matrices con Zarr:

  Copiado

  >>> import numpy as np
  >>> import zarr
  
  >>> embeddings = np.random.randn(50000, 1000).astype("float32")
  
  >>> # Write an array to a repo
  >>> root = zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w")
  >>> foo = root.create_group("embeddings")
  >>> foobar = foo.zeros(name="experiment_0", shape=(50000, 1000), chunks=(10000, 1000), dtype="f4")
  >>> foobar[:] = embeddings
  
  >>> # Read an array from a repo
  >>> root = zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r")
  >>> first_row = root["embeddings/experiment_0"][0]

Autenticación

En muchos casos, debes iniciar sesión con una cuenta de Hugging Face para interactuar con el Hub. Consulta la sección Authentication de la documentación para obtener más información sobre los métodos de autenticación en el Hub.

También es posible iniciar sesión de forma programática pasando su token como argumento a HfFileSystem:

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

Si inicias sesión de esta manera, ten cuidado de no filtrar accidentalmente el token al compartir tu código fuente.