Hugging Face's logo

Hub Python Library documentation

Descarga de archivos

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Descarga de archivos

Descargar un solo archivo

hf_hub_download

huggingface_hub.hf_hub_download

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Noneuser_agent: dict | str | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falseheaders: dict[str, str] | None = Noneendpoint: str | None = Nonetqdm_class: type[tqdm.std.tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo

Parámetros

  • repo_id (str) — El nombre de un usuario u organización y el nombre de un repositorio, separados por una /.
  • filename (str) — El nombre del archivo en el repositorio.
  • subfolder (str, opcional) — Un valor opcional que corresponde a una carpeta dentro del repositorio del modelo.
  • repo_type (str, opcional) — Establecer en "dataset", "space" o "kernel" si se descarga de un repositorio de dataset, space o kernel, None o "model" si se descarga de un modelo. El valor predeterminado es None.
  • revision (str, opcional) — Un identificador de revisión de Git opcional, que puede ser un nombre de rama, una etiqueta o un hash de commit.
  • library_name (str, opcional) — El nombre de la biblioteca a la que corresponde el objeto.
  • library_version (str, opcional) — La versión de la biblioteca.
  • cache_dir (str, Path, opcional) — Ruta de la carpeta donde se almacenan los archivos en caché.
  • local_dir (str o Path, opcional) — Si se proporciona, el archivo descargado se colocará en este directorio.
  • user_agent (dict, str, opcional) — La información del user-agent en forma de diccionario o cadena de caracteres.
  • force_download (bool, opcional, valor predeterminado False) — Si el archivo debe descargarse aunque ya exista en la caché local.
  • etag_timeout (float, opcional, valor predeterminado 10) — Al obtener el ETag, cuántos segundos esperar a que el servidor envíe datos antes de abandonar la operación, valor que se pasa a httpx2.request.
  • token (str, bool, opcional) — Un token para usar en la descarga.
    • Si True, el token se lee desde la carpeta de configuración de HuggingFace.
    • Si es una cadena de caracteres, se utiliza como token de autenticación.
  • local_files_only (bool, opcional, valor predeterminado False) — Si True, evita descargar el archivo y devuelve la ruta al archivo en caché local si existe.
  • headers (dict, opcional) — Encabezados adicionales que se enviarán con la solicitud.
  • endpoint (str, opcional) — El endpoint del Hub al que se envía la solicitud. El valor predeterminado es el de HF_ENDPOINT.
  • tqdm_class (tqdm, opcional) — Si se proporciona, sobrescribe el comportamiento predeterminado de la barra de progreso. El argumento pasado debe heredar de tqdm.auto.tqdm o al menos imitar su comportamiento. Por defecto, se utiliza la barra de progreso personalizada de HF, que se puede desactivar estableciendo la variable de entorno HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, opcional, valor predeterminado False) — Si True, realiza una ejecución de prueba sin descargar realmente el archivo. Devuelve un objeto DryRunFileInfo que contiene información sobre lo que se descargaría.

Devuelve

str o DryRunFileInfo

  • Si dry_run=False: ruta local del archivo o, si la red está desactivada, la última versión del archivo en caché en el disco.
  • Si dry_run=True: un objeto DryRunFileInfo que contiene información de descarga.

Lanza

RepositoryNotFoundError o RevisionNotFoundError o ~utils.RemoteEntryNotFoundError o LocalEntryNotFoundError o EnvironmentError o OSError o ValueError

  • RepositoryNotFoundError — Si no se puede encontrar el repositorio del que se va a descargar. Esto puede deberse a que no existe o a que está configurado como private y no tienes acceso.
  • RevisionNotFoundError — Si no se puede encontrar la revisión desde la que se debe descargar.
  • ~utils.RemoteEntryNotFoundError — Si no se puede encontrar el archivo para descargar.
  • LocalEntryNotFoundError — Si la red está deshabilitada o no está disponible y el archivo no se encuentra en la caché.
  • EnvironmentError — Si token=True pero no se puede encontrar el token.
  • OSError — Si no se puede determinar el ETag.
  • ValueError — Si el valor de algún parámetro no es válido.

Descarga un archivo dado si no está presente en la caché local.

El nuevo diseño de archivo de cacheta es el siguiente:

  • El directorio de caché contiene un subdirectorio por repo_id (espaciado de nombres por tipo de repositorio)
  • dentro de cada carpeta de repositorio:
    • refs es una lista de los pares de revisión => commit_hash más recientes conocidos
    • blobs contiene los blobs de archivo reales (identificados por su git-sha o sha256, dependiendo de si son archivos LFS o no)
    • snapshots contiene un subdirectorio por commit, y cada “commit” contiene el subconjunto de archivos que se han resuelto en ese commit en particular. Cada nombre de archivo es un enlace simbólico al blob en ese commit en particular.
[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

Si se proporciona local_dir, la estructura de archivos del repositorio se replicará en esta ubicación. Al usar esta opción, no se utilizará cache_dir y se creará una carpeta .cache/huggingface/ en la raíz de local_dir para almacenar algunos metadatos relacionados con los archivos descargados. Aunque este mecanismo no es tan robusto como el sistema de caché principal, está optimizado para obtener regularmente la última versión de un repositorio.

hf_hub_url

huggingface_hub.hf_hub_url

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )

Parámetros

  • repo_id (str) — Un nombre de espacio de nombres (usuario u organización) y un nombre de repositorio separados por una /.
  • filename (str) — El nombre del archivo en el repositorio.
  • subfolder (str, opcional) — Un valor opcional que corresponde a una carpeta dentro del repositorio.
  • repo_type (str, opcional) — Establecer en "dataset", "space" o "kernel" si se descarga de un repositorio de dataset, space o kernel, None o "model" si se descarga de un modelo. El valor predeterminado es None.
  • revision (str, opcional) — Un identificador de revisión de Git opcional, que puede ser un nombre de rama, una etiqueta o un hash de commit.
  • endpoint (str, opcional) — El endpoint del Hub al que se envía la solicitud. El valor predeterminado es el de HF_ENDPOINT.

Construya la URL de un archivo a partir de la información proporcionada.

La dirección resuelta puede ser una URL alojada en huggingface.co o un enlace a Cloudfront (una red de distribución de contenido, o CDN) para archivos grandes de más de unos pocos MB.

Ejemplo:

>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'

Notas:

Cloudfront se replica en todo el mundo, por lo que las descargas son mucho más rápidas para el usuario final (y también reduce nuestros costos de ancho de banda).

Cloudfront almacena en caché los archivos de forma agresiva por defecto (el TTL predeterminado es de 24 horas), sin embargo, esto no es un problema aquí porque implementamos un sistema de versionado basado en git en huggingface.co, lo que significa que almacenamos los archivos en S3/Cloudfront de una forma direccionable por contenido (es decir, el nombre del archivo es su hash). El uso de nombres de archivo direccionables por contenido significa que la caché nunca puede estar desactualizada.

En cuanto a la caché del lado del cliente de esta biblioteca, basamos nuestra caché en la etiqueta de entidad (ETag) de los objetos, que es un identificador de una versión específica de un recurso [1]_. El ETag de un objeto es: su git-sha1 si está almacenado en git, o su sha256 si está almacenado en git-lfs.

Referencias:

Descarga una instantánea del repositorio

huggingface_hub.snapshot_download

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[tqdm.asyncio.tqdm_asyncio] | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo

Parámetros

  • repo_id (str) — El nombre de un usuario u organización y el nombre de un repositorio, separados por una /.
  • repo_type (str, opcional) — Establecer en "dataset", "space" o "kernel" si se descarga de un repositorio de dataset, space o kernel, None o "model" si se descarga de un modelo. El valor predeterminado es None.
  • revision (str, opcional) — Un identificador de revisión de Git opcional, que puede ser un nombre de rama, una etiqueta o un hash de commit.
  • cache_dir (str, Path, opcional) — Ruta de la carpeta donde se almacenan los archivos en caché.
  • local_dir (str o Path, opcional) — Si se proporciona, los archivos descargados se colocarán en este directorio.
  • library_name (str, opcional) — El nombre de la biblioteca a la que corresponde el objeto.
  • library_version (str, opcional) — La versión de la biblioteca.
  • user_agent (str, dict, opcional) — La información del user-agent en forma de diccionario o cadena de caracteres.
  • etag_timeout (float, opcional, valor predeterminado 10) — Al obtener el ETag, cuántos segundos esperar a que el servidor envíe datos antes de abandonar la operación, valor que se pasa a httpx2.request.
  • force_download (bool, opcional, valor predeterminado False) — Si el archivo debe descargarse aunque ya exista en la caché local.
  • token (str, bool, opcional) — Un token para usar en la descarga.
    • Si True, el token se lee desde la carpeta de configuración de HuggingFace.
    • Si es una cadena de caracteres, se utiliza como token de autenticación.
  • headers (dict, opcional) — Encabezados adicionales para incluir en la solicitud. Estos encabezados tienen prioridad sobre los demás.
  • endpoint (str, opcional) — El endpoint del Hub al que se envía la solicitud. El valor predeterminado es el de HF_ENDPOINT.
  • local_files_only (bool, opcional, valor predeterminado False) — Si True, no descargue ningún archivo, incluso si no están en cache_dir o local_dir.
  • allow_patterns (list[str] o str, opcional) — Si se proporciona, solo se descargan los archivos que coincidan con al menos un patrón.
  • ignore_patterns (list[str] o str, opcional) — Si se proporciona, los archivos que coincidan con cualquiera de los patrones no se descargarán.
  • max_workers (int, opcional) — Número de hilos concurrentes para descargar archivos (1 hilo = 1 descarga de archivo). El valor predeterminado es 8.
  • tqdm_class (tqdm, opcional) — Si se proporciona, sobrescribe el comportamiento predeterminado de la barra de progreso. El argumento pasado debe heredar de tqdm.auto.tqdm o al menos imitar su comportamiento. Tenga en cuenta que tqdm_class no se pasa a cada descarga individual. Por defecto, se utiliza la barra de progreso personalizada de HF, que se puede desactivar estableciendo la variable de entorno HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, opcional, valor predeterminado False) — Si True, realiza una ejecución de prueba sin descargar realmente los archivos. Devuelve una lista de objetos DryRunFileInfo que contienen información sobre lo que se descargaría.

Devuelve

str o lista de DryRunFileInfo

  • Si dry_run=False: Ruta local de la instantánea.
  • Si dry_run=True: una lista de objetos DryRunFileInfo que contienen información de descarga.

Lanza

RepositoryNotFoundError o RevisionNotFoundError o IncompleteSnapshotError o EnvironmentError o OSError o ValueError

  • RepositoryNotFoundError — Si no se puede encontrar el repositorio del que se va a descargar. Esto puede deberse a que no existe o a que está configurado como private y no tienes acceso.
  • RevisionNotFoundError — Si no se puede encontrar la revisión desde la que se debe descargar.
  • IncompleteSnapshotError — Si no se puede acceder al Hub (sin conexión, problema de conexión o local_files_only=True) y la instantánea en caché no contiene algunos de los archivos solicitados.
  • EnvironmentError — Si token=True y no se puede encontrar el token.
  • OSError — si no se puede determinar el ETag.
  • ValueError — Si el valor de algún parámetro no es válido.

Descarga los archivos del repositorio.

Descarga un instantáneo completo de los archivos de un repositorio en la revisión especificada. Esto es útil cuando quieres todos los archivos de un repositorio porque no sabes cuáles necesitarás a priori. Todos los archivos se anidan en una carpeta para mantener su ruta y nombre de archivo relativos a esa carpeta. También puedes filtrar qué archivos descargar usando allow_patterns y ignore_patterns.

Si se proporciona local_dir, la estructura de archivos del repositorio se replicará en esta ubicación. Al usar esta opción, no se utilizará cache_dir y se creará una carpeta .cache/huggingface/ en la raíz de local_dir para almacenar algunos metadatos relacionados con los archivos descargados. Aunque este mecanismo no es tan robusto como el sistema de caché principal, está optimizado para obtener regularmente la última versión de un repositorio.

Una alternativa sería clonar el repositorio, pero esto requiere que git y git-lfs estén instalados y configurados correctamente. Además, no es posible filtrar qué archivos descargar al clonar un repositorio usando git.

Leer el árbol del repositorio en caché

huggingface_hub.get_cached_repo_tree

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = None ) → list[RepoFile]

Parámetros

  • repo_id (str) — El nombre de un usuario u organización y el nombre de un repositorio, separados por una /.
  • repo_type (str, opcional) — Establecer en "dataset", "space" o "kernel" si se lista desde un repositorio de dataset, space o kernel, None o "model" si se lista desde un modelo. El valor predeterminado es None.
  • revision (str, opcional) — Un identificador de revisión de Git opcional, que puede ser un nombre de rama, una etiqueta o un hash de commit. El valor predeterminado es la rama predeterminada. Los nombres de rama/etiqueta se resuelven a un hash de commit usando la caché local (refs/).
  • cache_dir (str, Path, opcional) — Ruta de la carpeta donde se almacenan los archivos en caché. El valor predeterminado es el de HF_HUB_CACHE.
  • local_dir (str o Path, opcional) — Si se proporciona, lee el listado del árbol cacheado por una descarga de local_dir (desde local_dir/.cache/huggingface/) en lugar de la caché principal. Las revisiones de rama/etiqueta se resuelven todavía a un hash de commit usando la caché principal (cache_dir).

Devuelve

list[RepoFile]

La lista de objetos RepoFile en caché para esta revisión.

Lanza

CachedRepoTreeNotFoundError

  • CachedRepoTreeNotFoundError — Si no hay un listado de árbol en caché para la revisión solicitada (p. ej., el repositorio nunca se descargó en esta revisión).

Devuelve la lista de árbol en caché de un repositorio en una revisión dada, sin ninguna llamada de red.

La lista de árbol es el conjunto de archivos (con sus metadatos de descarga) de un repositorio en un commit. Se genera en disco como efecto secundario de snapshot_download() (consulte los archivos de caché trees/<commit_hash>.json) y se utiliza para omitir las llamadas de red en descargas posteriores. Esta función expone directamente esa caché.

Si necesitas la lista actual del árbol de un repositorio en el Hub, usa list_repo_tree() en su lugar.

Ejemplo:

>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]

Resolver una revisión

Resuelva un nombre de rama o etiqueta a un hash de commit una sola vez y luego pase el resultado para fijar todas las descargas al mismo commit. Consulte HfApi.resolve_revision() y la guía del sistema de caché.

ResolvedRevision

clase huggingface_hub.ResolvedRevision

< >

( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )

Parámetros

  • initial (str or None) — La revisión solicitada inicialmente por el usuario. Si es None, el valor de la cadena predeterminado es "main".
  • resolved (str) — El hash del commit al que initial se resuelve.

Una revisión de git que ya se ha resuelto a un hash de commit.

ResolvedRevision es una subclase de str, por lo que se puede pasar a cualquier método de huggingface_hub que acepte un argumento revision. Su valor de cadena es la revisión solicitada inicialmente por el usuario (p. ej. "main", "refs/pr/4"), lo que mantiene las URL y los mensajes de error legibles, mientras que .resolved contiene el hash del commit al que apunta.

Las instancias se construyen mediante HfApi.resolve_revision(), que también almacena en caché local (carpeta refs/) el mapeo de revision -> commit hash.

Un hash de commit solo tiene significado para el repositorio contra el que se resolvió, por lo que una instancia también recuerda ese repositorio. Volver a resolverlo para otro repositorio no es un error: se vuelve a resolver la revisión solicitada inicialmente (ver HfApi.resolve_revision()).

Ejemplo:

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

Obtener metadatos sobre un archivo

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< >

( url: strtoken: bool | str | None = Nonetimeout: float | None = 10library_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Noneretry_on_errors: bool = False )

Parámetros

  • url (str) — URL del archivo, por ejemplo, la devuelta por hf_hub_url().
  • token (str o bool, opcional) — Un token que se usará para la descarga. Si es True, el token se lee desde la carpeta de configuración de HuggingFace. Si es False o None, no se proporciona ningún token. Si es una cadena, se usa como token de autenticación.
    • Si True, el token se lee desde la carpeta de configuración de HuggingFace.
    • Si False o None, no se proporciona ningún token.
    • Si es una cadena de caracteres, se utiliza como token de autenticación.
  • timeout (float, opcional, valor predeterminado 10) — Número de segundos que se espera a que el servidor envíe los metadatos antes de abandonar la espera.
  • library_name (str, opcional) — El nombre de la biblioteca a la que corresponde el objeto.
  • library_version (str, opcional) — La versión de la biblioteca.
  • user_agent (dict, str, opcional) — La información del user-agent en forma de diccionario o cadena de caracteres.
  • headers (dict, opcional) — Encabezados adicionales que se enviarán con la solicitud.
  • endpoint (str, opcional) — Endpoint del Hub. El valor predeterminado es https://huggingface.co.
  • retry_on_errors (bool, opcional, valor predeterminado False) — Si se deben reintentar los errores (429, 5xx, timeout, errores de red). Si es False, no se realiza ningún reintento para un cambio rápido a la caché local.

Obtener los metadatos de un archivo versionado en el Hub para una URL dada.

HfFileMetadata

clase huggingface_hub.HfFileMetadata

< >

( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )

Parámetros

  • commit_hash (str, opcional) — El commit_hash relacionado con el archivo.
  • etag (str, opcional) — Etag del archivo en el servidor.
  • location (str) — Ubicación donde descargar el archivo. Puede ser una URL de Hub o no (CDN).
  • size (size) — Tamaño del archivo. En el caso de un archivo LFS, contiene el tamaño del archivo LFS real, no el del puntero.
  • xet_file_data (XetFileData, opcional) — Información de Xet para el archivo. Esto solo se establece si el archivo se almacena usando el almacenamiento de Xet.

Estructura de datos que contiene información sobre un archivo versionado en el Hub.

Devuelto por get_hf_file_metadata() en función de una URL.

Caché

Los métodos mostrados anteriormente están diseñados para funcionar con un sistema de caché que evita la descarga repetida de archivos. El sistema de caché se actualizó en la v0.8.0 para convertirse en el sistema de caché central compartido entre las bibliotecas que dependen del Hub.

Lea la guía del sistema de caché para una presentación detallada de la caché en HF.

Update on GitHub

←CLI Mixins y métodos de serialización→