API del sistema de archivos

La clase HfFileSystem proporciona una interfaz de archivos pythonic para el Hugging Face Hub basada en fsspec.

HfFileSystem

HfFileSystem se basa en fsspec, por lo que es compatible con la mayoría de las APIs que ofrece. Para más detalles, consulta nuestra guía y la API Reference de fsspec.

clase huggingface_hub.HfFileSystem

< source >

( *args**kwargs )

Parámetros

endpoint (str, opcional) — Endpoint del Hub. El valor predeterminado es https://huggingface.co.
token (bool o str, opcional) — Un token de acceso de usuario válido (cadena). Por defecto, se utiliza el token guardado localmente, que es el método recomendado para la autenticación (ver https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Para deshabilitar la autenticación, pase False.
block_size (int, opcional) — Tamaño de bloque para la lectura y escritura de archivos.
expand_info (bool, opcional) — Si se debe expandir la información de los archivos.
max_workers (int, opcional) — Número máximo de solicitudes concurrentes utilizadas para listar directorios grandes en paralelo (ver find()). El valor predeterminado es 16. Establézcalo en 1 para deshabilitar las listaciones paralelas.
live_follow (bool, opcional) — Si se siguen los cambios de archivos en los buckets a medida que ocurren en el Hub, para que las listas en caché se mantengan actualizadas sin llamadas manuales a HfFileSystem.invalidate_cache(). Cuando está habilitado, listar un bucket abre una conexión en segundo plano al feed de eventos del Hub para ese bucket. No tiene efecto en los repositorios de modelos, datasets y spaces (el Hub no emite cambios para esos).
**storage_options (dict, opcional) — Opciones adicionales para el sistema de archivos. Consulte la documentación de fsspec.

Acceda a un repositorio remoto de Hugging Face Hub como si fuera un sistema de archivos local.

HfFileSystem ofrece compatibilidad con fsspec, lo cual es útil para bibliotecas que la requieren (por ejemplo, para leer conjuntos de datos 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.

El sistema de archivos admite rutas para el protocolo hf://, que sigue los siguientes esquemas de URL:

Repositorios de modelos, conjuntos de datos y Spaces:

hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>

Buckets (almacenamiento genérico):

hf://buckets/<bucket-id>/<path/in/bucket>

Nota: al usar HfFileSystem directamente, el prefijo de protocolo hf:// es opcional en las rutas.

Uso:

>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)

Especifique un token para la autenticación:

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

cp_file

< source >

( path1: strpath2: strrevision: str | None = None**kwargs )

Parámetros

path1 (str) — Ruta de origen desde la que copiar.
path2 (str) — Ruta de destino a la que copiar.
revision (str, opcional) — La revisión de git desde la que copiar.

Copie un archivo dentro de un repositorio, entre repositorios o a un bucket.

Nota: Cuando sea posible, use HfApi.upload_file() para un mejor rendimiento.

existe

< source >

( path**kwargs ) → bool

Parámetros

path (str) — Ruta a verificar.

Devuelve

bool

True si el archivo existe, False en caso contrario.

Comprueba si un archivo existe.

Para más detalles, consulte la documentación de fsspec.

Nota: Cuando sea posible, use HfApi.file_exists() para un mejor rendimiento.

find

< source >

( path: strmaxdepth: int | None = Nonewithdirs: bool = Falsedetail: bool = Falserefresh: bool = Falserevision: str | None = None**kwargs ) → Union[list[str], dict[str, dict[str, Any]]]

Parámetros

path (str) — Ruta raíz desde la que listar los archivos.
maxdepth (int, opcional) — Profundidad máxima a la que descender en los subdirectorios.
withdirs (bool, opcional) — Incluye las rutas de los directorios en la salida. El valor predeterminado es False.
detail (bool, opcional) — Si es True, devuelve un dict que mapea rutas a información de archivo. El valor predeterminado es False.
refresh (bool, opcional) — Si es True, se omite la caché y se obtienen los datos más recientes. El valor predeterminado es False.
revision (str, opcional) — La revisión de git desde la que se listará.

Devuelve

Union[list[str], dict[str, dict[str, Any]]]

Lista de rutas o diccionario de información de archivos.

Listar todos los archivos bajo la ruta.

Para más detalles, consulte la documentación de fsspec.

Los repositorios grandes se enumeran directorio por directorio, en paralelo, para sortear la paginación basada en cursores del punto final tree del Hub. Ajusta esto con el argumento max_workers de HfFileSystem.

get_file

< source >

( rpathlpath = Nonecallback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>outfile = None**kwargs )

Parámetros

rpath (str) — Ruta remota desde la que descargar.
lpath (str, opcional) — Ruta local de descarga. Se puede omitir si se proporciona outfile.
callback (Callback, optional) — Optional callback to track download progress. Defaults to no callback.
outfile (IO, opcional) — Objeto similar a un archivo opcional para escribir. Si se proporciona, lpath se ignora.

Copiar un archivo remoto individual a local.

Nota: Cuando sea posible, use HfApi.hf_hub_download() o HfApi.download_bucket_files para un mejor rendimiento.

glob

< source >

( path: strmaxdepth: int | None = None**kwargs ) → list[str]

Parámetros

path (str) — Patrón de ruta para coincidir.
maxdepth (int, opcional) — Profundidad máxima a la que descender en los directorios. Por defecto, no hay límite.

Devuelve

list[str]

Lista de rutas que coinciden con el patrón.

Encuentra archivos mediante coincidencia de glob.

Para más detalles, consulte la documentación de fsspec.

info

< source >

( path: strrefresh: bool = Falserevision: str | None = None**kwargs ) → dict[str, Any]

Parámetros

path (str) — Ruta para la que obtener información.
refresh (bool, opcional) — Si es True, se omite la caché y se obtienen los datos más recientes. El valor predeterminado es False.
revision (str, opcional) — La revisión de git de la que obtener información.

Devuelve

dict[str, Any]

Diccionario que contiene información del archivo (tipo, tamaño, información del commit, etc.).

Obtén información sobre un archivo o directorio.

Para más detalles, consulte la documentación de fsspec.

Nota: Cuando sea posible, use HfApi.get_paths_info() o HfApi.repo_info() para un mejor rendimiento (o HfApi.get_bucket_paths_info() o HfApi.bucket_info() para buckets)

invalidate_cache

< source >

( path: str | None = None )

Parámetros

path (str, opcional) — Ruta para limpiar de la caché. Si no se proporciona, se limpia toda la caché.

Borrar la caché para una ruta dada.

Para más detalles, consulte la documentación de fsspec.

isdir

< source >

( path ) → bool

Parámetros

path (str) — Ruta a verificar.

Devuelve

bool

True si path es un directorio, False en caso contrario.

Comprueba si una ruta es un directorio.

Para más detalles, consulte la documentación de fsspec.

isfile

< source >

( path ) → bool

Parámetros

path (str) — Ruta a verificar.

Devuelve

bool

True si path es un archivo, False en caso contrario.

Comprueba si una ruta es un archivo.

Para más detalles, consulte la documentación de fsspec.

ls

< source >

( path: strdetail: bool = Truerefresh: bool = Falserevision: str | None = None**kwargs ) → list[Union[str, dict[str, Any]]]

Parámetros

path (str) — Ruta al directorio.
detail (bool, opcional) — Si es True, devuelve una lista de diccionarios que contienen información del archivo. Si es False, devuelve una lista de rutas de archivo. El valor predeterminado es True.
refresh (bool, opcional) — Si es True, se omite la caché y se obtienen los datos más recientes. El valor predeterminado es False.
revision (str, opcional) — La revisión de git desde la que se listará.

Devuelve

list[Union[str, dict[str, Any]]]

Lista de rutas de archivo (si detail=False) o lista de diccionarios de información de archivo (si detail=True).

Listar el contenido de un directorio.

Para más detalles, consulte la documentación de fsspec.

Nota: Cuando sea posible, use HfApi.list_repo_tree() para un mejor rendimiento.

modificado

< source >

( path: str**kwargs ) → datetime

Parámetros

path (str) — Ruta al archivo.

Devuelve

datetime

Hora de última modificación del archivo.

Obtener la hora de la última modificación de un archivo.

Para más detalles, consulte la documentación de fsspec.

resolve_path

< source >

( path: strrevision: str | None = None ) → HfFileSystemResolvedPath

Parámetros

path (str) — Ruta a resolver.
revision (str, opcional) — La revisión del repositorio que se debe resolver. Por defecto, es la revisión especificada en la ruta.

Devuelve

HfFileSystemResolvedPath

Información de la ruta resuelta que contiene repo_type, repo_id, revision y path_in_repo.

Lanza

ValueError o NotImplementedError

ValueError — Si path contiene información de revisión conflictiva.
NotImplementedError — Si se intenta listar repositorios.

Resuelve una ruta del sistema de archivos de Hugging Face en sus componentes.

rm

< source >

( path: strrecursive: bool = Falsemaxdepth: int | None = Nonerevision: str | None = None**kwargs )

Parámetros

path (str) — Ruta a eliminar.
recursive (bool, opcional) — Si es True, elimina el directorio y todo su contenido. El valor predeterminado es False.
maxdepth (int, opcional) — Número máximo de subdirectorios a visitar al eliminar recursivamente.
revision (str, opcional) — La revisión de git desde la que se eliminará.

Eliminar archivos de un repositorio.

Para más detalles, consulte la documentación de fsspec.

Nota: Cuando sea posible, use HfApi.delete_file() para un mejor rendimiento.

url

< source >

( path: str ) → str

Parámetros

path (str) — Ruta para obtener la URL.

Devuelve

str

URL HTTP para acceder al archivo o directorio en el Hub.

Obtenga la URL HTTP de la ruta indicada.

recorrer

< source >

( path: str*args**kwargs ) → Iterator[tuple[str, list[str], list[str]]]

Parámetros

path (str) — Ruta raíz desde la que listar los archivos.

Devuelve

Iterator[tuple[str, list[str], list[str]]]

Un iterador de tuplas (ruta, lista de nombres de directorios, lista de nombres de archivos).

Devuelve todos los archivos bajo la ruta indicada.

Para más detalles, consulte la documentación de fsspec.

Update on GitHub

Hub Python Library

API del sistema de archivos

HfFileSystem

clase huggingface_hub.HfFileSystem

cp_file

existe

find

get_file

glob

info

invalidate_cache

isdir

isfile

ls

modificado

resolve_path

rm

url

recorrer