Hub Python Library documentation

Referencia del sistema de caché

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Referencia del sistema de caché

El sistema de caché se actualizó en 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 del almacenamiento en caché en HF.

Funciones auxiliares

try_to_load_from_cache

huggingface_hub.try_to_load_from_cache

( repo_id: strfilename: strcache_dir: str | pathlib.Path | None = Nonerevision: str | None = Nonerepo_type: str | None = None ) → Optional[str] or _CACHED_NO_EXIST

Parámetros

cache_dir (str o os.PathLike) — La carpeta donde se encuentran los archivos en caché.
repo_id (str) — El ID del repositorio en huggingface.co.
filename (str) — El nombre del archivo que se buscará dentro de repo_id.
revision (str, opcional) — La versión específica del modelo que se utilizará. Si no se proporciona y tampoco se indica un commit_hash, se usará "main" de forma predeterminada.
repo_type (str, opcional) — El tipo de repositorio. El valor predeterminado es "model".

Devuelve

Optional[str] o _CACHED_NO_EXIST

Devolverá None si el archivo no estaba en caché. En caso contrario:

La ruta exacta del archivo en caché si se encuentra en la caché
Un valor especial _CACHED_NO_EXIST si el archivo no existe en el hash de commit dado y este hecho fue cacheado.

Explora la caché para devolver el archivo más reciente en caché para una revisión dada, si se encuentra.

Esta función no lanzará ninguna excepción si el archivo no está en caché.

Ejemplo:

from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST

filepath = try_to_load_from_cache()
if isinstance(filepath, str):
    # file exists and is cached
    ...
elif filepath is _CACHED_NO_EXIST:
    # non-existence of file is cached
    ...
else:
    # file is not cached
    ...

cached_assets_path

huggingface_hub.cached_assets_path

( library_name: strnamespace: str = 'default'subfolder: str = 'default'assets_dir: str | pathlib.Path | None = None )

Parámetros

library_name (str) — Nombre de la biblioteca que gestionará la carpeta de caché. Ejemplo: "dataset".
namespace (str, opcional, valor predeterminado “default”) — Espacio de nombres al que pertenecen los datos. Ejemplo: "SQuAD".
subfolder (str, opcional, valor predeterminado “default”) — Subcarpeta en la que se almacenarán los datos. Ejemplo: extracted.
assets_dir (str, Path, opcional) — Ruta de la carpeta donde se almacenan los recursos en caché. Esto no debe ser la misma carpeta donde se almacenan en caché los archivos de Hub. El valor predeterminado es HF_HOME / "assets" si no se proporciona. También se puede configurar con la variable de entorno HF_ASSETS_CACHE.

Devuelve una ruta de carpeta para cachear archivos arbitrarios.

huggingface_hub proporciona una ruta de carpeta canónica para almacenar recursos. Esta es la forma recomendada de integrar la caché en una biblioteca de nivel inferior, ya que se beneficiará de las herramientas integradas para escanear y eliminar la caché correctamente.

La distinción se establece entre los archivos cacheados desde el Hub y los recursos. Los archivos del Hub se cachean de manera consciente de git y son gestionados por completo por huggingface_hub. Consulte la documentación relacionada. Todos los demás archivos que una biblioteca de nivel inferior cachea se consideran “recursos” (archivos descargados de fuentes externas, extraídos de un archivo .tar, preprocesados para el entrenamiento,…).

Una vez que se genera la ruta de la carpeta, se garantiza que existe y que es un directorio. La ruta se basa en 3 niveles de profundidad: el nombre de la biblioteca, un espacio de nombres y una subcarpeta. Esos 3 niveles otorgan flexibilidad al mismo tiempo que permiten a huggingface_hub esperar carpetas al escanear o eliminar partes de la caché de activos. Dentro de una biblioteca, se espera que todos los espacios de nombres compartan el mismo subconjunto de nombres de subcarpetas, pero esta no es una regla obligatoria. La biblioteca de nivel inferior tiene entonces el control total sobre qué estructura de archivos adoptar dentro de su caché. El espacio de nombres y la subcarpeta son opcionales (por defecto, se usaría una subcarpeta "default/"), pero el nombre de la biblioteca es obligatorio, ya que queremos que cada biblioteca de nivel inferior gestione su propia caché.

Árbol esperado:

    assets/
    └── datasets/
    │   ├── SQuAD/
    │   │   ├── downloaded/
    │   │   ├── extracted/
    │   │   └── processed/
    │   ├── Helsinki-NLP--tatoeba_mt/
    │       ├── downloaded/
    │       ├── extracted/
    │       └── processed/
    └── transformers/
        ├── default/
        │   ├── something/
        ├── bert-base-cased/
        │   ├── default/
        │   └── training/
    hub/
    └── models--julien-c--EsperBERTo-small/
        ├── blobs/
        │   ├── (...)
        │   ├── (...)
        ├── refs/
        │   └── (...)
        └── [ 128]  snapshots/
            ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
            │   ├── (...)
            └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
                └── (...)

Ejemplo:

>>> from huggingface_hub import cached_assets_path

>>> cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/SQuAD/download')

>>> cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="extracted")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/SQuAD/extracted')

>>> cached_assets_path(library_name="datasets", namespace="Helsinki-NLP/tatoeba_mt")
PosixPath('/home/wauplin/.cache/huggingface/extra/datasets/Helsinki-NLP--tatoeba_mt/default')

>>> cached_assets_path(library_name="datasets", assets_dir="/tmp/tmp123456")
PosixPath('/tmp/tmp123456/datasets/default/default')

scan_cache_dir

huggingface_hub.scan_cache_dir

( cache_dir: str | pathlib.Path | None = None )

Parámetros

cache_dir (str or Path, optional) — Cache directory to cache. Defaults to the default HF cache directory.

Escanee todo el sistema de caché de HF y devuelva una estructura ~HFCacheInfo.

Use scan_cache_dir para escanear su sistema de caché de forma programática. La caché se escaneará repositorio por repositorio. Si un repositorio está corrupto, se lanzará internamente una ~CorruptedCacheException, pero se capturará y se devolverá en la estructura ~HFCacheInfo. Solo los repositorios válidos reciben un informe adecuado.

>>> from huggingface_hub import scan_cache_dir

>>> hf_cache_info = scan_cache_dir()
HFCacheInfo(
    size_on_disk=3398085269,
    repos=frozenset({
        CachedRepoInfo(
            repo_id='t5-small',
            repo_type='model',
            repo_path=PosixPath(...),
            size_on_disk=970726914,
            nb_files=11,
            revisions=frozenset({
                CachedRevisionInfo(
                    commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5',
                    size_on_disk=970726339,
                    snapshot_path=PosixPath(...),
                    files=frozenset({
                        CachedFileInfo(
                            file_name='config.json',
                            size_on_disk=1197
                            file_path=PosixPath(...),
                            blob_path=PosixPath(...),
                        ),
                        CachedFileInfo(...),
                        ...
                    }),
                ),
                CachedRevisionInfo(...),
                ...
            }),
        ),
        CachedRepoInfo(...),
        ...
    }),
    warnings=[
        CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."),
        CorruptedCacheException(...),
        ...
    ],
)

También puede imprimir un informe detallado directamente desde la línea de comandos hf usando:

> hf cache ls
ID                          SIZE     LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue          157.4M 2 days ago    2 days ago    main script
model/LiquidAI/LFM2-VL-1.6B     3.2G 4 days ago    4 days ago    main
model/microsoft/UserLM-8b      32.1G 4 days ago    4 days ago    main

Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G.
Got 1 warning(s) while scanning. Use -vvv to print details.

Excepciones:

CacheNotFound Si el directorio de caché no existe.

ValueError Si el directorio de caché es un archivo, en lugar de un directorio.

Devuelve: un objeto ~HFCacheInfo.

Estructuras de datos

Todas las estructuras se construyen y devuelven mediante scan_cache_dir() y son inmutables.

HFCacheInfo

clase huggingface_hub.HFCacheInfo

( size_on_disk: intrepos: frozensetincomplete_files: frozensetwarnings: listcache_dir: pathlib.Path | None = None )

Parámetros

size_on_disk (int) — Tamaño físico del sistema de caché en bytes. Un blob compartido entre repositorios se cuenta una sola vez, y los blobs compartidos solo en el almacén que ya no son referenciados por ningún repositorio se incluyen. Puede ser menor que la suma de los tamaños por repositorio.
repos (frozenset[CachedRepoInfo]) — Conjunto de ~CachedRepoInfo que describe todos los repositorios en caché válidos encontrados en el sistema de caché durante la exploración.
incomplete_files (frozenset[CachedIncompleteFileInfo]) — Conjunto de ~CachedIncompleteFileInfo que describe los archivos huérfanos *.incomplete dejados atrás por descargas interrumpidas.
warnings (list[CorruptedCacheException]) — Lista de ~CorruptedCacheException que se produjeron durante el análisis de la caché. Esas excepciones se capturan para que el análisis pueda continuar. Los repositorios corruptos se omiten en el análisis.
cache_dir (Path o None) — Directorio de caché que se escaneó.

Estructura de datos inmutable que contiene información sobre todo el sistema de caché.

Esta estructura de datos es devuelta por scan_cache_dir() y es inmutable.

size_on_disk solo tiene en cuenta los blobs y se omiten los repositorios corruptos. Es un tamaño físico: a diferencia de CachedRepoInfo.size_on_disk, que atribuye un blob compartido a cada repositorio que lo referencia, un blob compartido se cuenta aquí solo una vez.

delete_files

( *files: CachedFileInfo )

Prepara la estrategia para eliminar archivos individuales en caché.

Solo se eliminan las entradas de la instantánea. Un blob se elimina solo si ningún otro archivo en caché lo referencia, por lo que los blobs compartidos con otras revisiones se conservan. Las referencias y los directorios de instantáneas también se conservan, incluso si una instantánea termina vacía. Para eliminar revisiones o repositorios completos, usa delete_revisions().

Ejemplo:

>>> from huggingface_hub import scan_cache_dir
>>> cache_info = scan_cache_dir()
>>> files = [
...     file
...     for repo in cache_info.repos
...     if repo.repo_id == "org/model"
...     for revision in repo.revisions
...     for file in revision.files
...     if file.file_name == "model-Q4_K_M.gguf"
... ]
>>> delete_strategy = cache_info.delete_files(*files)
>>> print(f"Will free {delete_strategy.expected_freed_size_str}.")
Will free 4.9G.
>>> delete_strategy.execute()

delete_revisions

( *revisions: str )

Prepara la estrategia para eliminar una o más revisiones almacenadas en caché localmente.

Las revisiones de entrada pueden ser cualquier hash de revisión. Si un hash de revisión no se encuentra en la caché local, se emite una advertencia pero no se lanza un error. Las revisiones pueden provenir de repositorios en caché diferentes, ya que los hashes son únicos entre repositorios,

Ejemplos:

>>> from huggingface_hub import scan_cache_dir
>>> cache_info = scan_cache_dir()
>>> delete_strategy = cache_info.delete_revisions(
...     "81fd1d6e7847c99f5862c9fb81387956d99ec7aa"
... )
>>> print(f"Will free {delete_strategy.expected_freed_size_str}.")
Will free 7.9K.
>>> delete_strategy.execute()

>>> from huggingface_hub import scan_cache_dir
>>> scan_cache_dir().delete_revisions(
...     "81fd1d6e7847c99f5862c9fb81387956d99ec7aa",
...     "e2983b237dccf3ab4937c97fa717319a9ca1a96d",
...     "6c0e6080953db56375760c0471a8c5f2929baf11",
... ).execute()

delete_revisions devuelve un objeto DeleteCacheStrategy que debe ejecutarse. El DeleteCacheStrategy no está diseñado para ser modificado, pero permite realizar una ejecución de prueba antes de ejecutar la eliminación de forma real.

export_as_table

( verbosity: int = 0 ) → str

Parámetros

verbosity (int, opcional) — Nivel de detalle. El valor predeterminado es 0.

Devuelve

str

La tabla como una cadena de caracteres.

Genere una tabla a partir del objeto HFCacheInfo.

Pasa verbosity=0 para obtener una tabla con una fila por repositorio, con las columnas “repo_id”, “repo_type”, “size_on_disk”, “nb_files”, “last_accessed”, “last_modified”, “refs”, “local_path”.

Pasa verbosity=1 para obtener una tabla con una fila por repositorio y revisión (por lo que pueden aparecer varias filas para un solo repositorio), con las columnas “repo_id”, “repo_type”, “revision”, “size_on_disk”, “nb_files”, “last_modified”, “refs”, “local_path”.

Ejemplo:

>>> from huggingface_hub.utils import scan_cache_dir

>>> hf_cache_info = scan_cache_dir()
HFCacheInfo(...)

>>> print(hf_cache_info.export_as_table())
REPO ID                                             REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS LOCAL PATH
--------------------------------------------------- --------- ------------ -------- ------------- ------------- ---- --------------------------------------------------------------------------------------------------
roberta-base                                        model             2.7M        5 1 day ago     1 week ago    main ~/.cache/huggingface/hub/models--roberta-base
suno/bark                                           model             8.8K        1 1 week ago    1 week ago    main ~/.cache/huggingface/hub/models--suno--bark
t5-base                                             model           893.8M        4 4 days ago    7 months ago  main ~/.cache/huggingface/hub/models--t5-base
t5-large                                            model             3.0G        4 5 weeks ago   5 months ago  main ~/.cache/huggingface/hub/models--t5-large

>>> print(hf_cache_info.export_as_table(verbosity=1))
REPO ID                                             REPO TYPE REVISION                                 SIZE ON DISK NB FILES LAST_MODIFIED REFS LOCAL PATH
--------------------------------------------------- --------- ---------------------------------------- ------------ -------- ------------- ---- -----------------------------------------------------------------------------------------------------------------------------------------------------
roberta-base                                        model     e2da8e2f811d1448a5b465c236feacd80ffbac7b         2.7M        5 1 week ago    main ~/.cache/huggingface/hub/models--roberta-base/snapshots/e2da8e2f811d1448a5b465c236feacd80ffbac7b
suno/bark                                           model     70a8a7d34168586dc5d028fa9666aceade177992         8.8K        1 1 week ago    main ~/.cache/huggingface/hub/models--suno--bark/snapshots/70a8a7d34168586dc5d028fa9666aceade177992
t5-base                                             model     a9723ea7f1b39c1eae772870f3b547bf6ef7e6c1       893.8M        4 7 months ago  main ~/.cache/huggingface/hub/models--t5-base/snapshots/a9723ea7f1b39c1eae772870f3b547bf6ef7e6c1
t5-large                                            model     150ebc2c4b72291e770f58e6057481c8d2ed331a         3.0G        4 5 months ago  main ~/.cache/huggingface/hub/models--t5-large/snapshots/150ebc2c4b72291e770f58e6057481c8d2ed331a

CachedRepoInfo

clase huggingface_hub.CachedRepoInfo

( repo_id: strrepo_type: typing.Literal['model', 'dataset', 'space', 'kernel']repo_path: Pathsize_on_disk: intnb_files: intrevisions: frozensetlast_accessed: floatlast_modified: float )

Parámetros

repo_id (str) — Id del repositorio en el Hub. Ejemplo: "google/fleurs".
repo_type (Literal["dataset", "model", "space", "kernel"]) — Tipo del repositorio en caché.
repo_path (Path) — Ruta local al repositorio en caché.
size_on_disk (int) — Suma de los tamaños de los archivos blob en el repositorio en caché.
nb_files (int) — Número total de archivos blob en el repositorio en caché.
revisions (frozenset[CachedRevisionInfo]) — Conjunto de ~CachedRevisionInfo que describe todas las revisiones en caché del repositorio.
last_accessed (float) — Marca de tiempo de la última vez que se accedió a un archivo blob del repositorio.
last_modified (float) — Marca de tiempo de la última modificación o creación de un archivo blob del repositorio.

Estructura de datos inmutable que contiene información sobre un repositorio en caché.

size_on_disk no es necesariamente la suma de los tamaños de todas las revisiones debido a los archivos duplicados. Además, solo se tienen en cuenta los blobs, no el (despreciable) tamaño de las carpetas y los enlaces simbólicos.

La fiabilidad de last_accessed y last_modified puede depender del sistema operativo que estés utilizando. Consulta la documentación de Python para más detalles.

size_on_disk_str

( )

(property) Suma de los tamaños de los archivos blob como una cadena legible por humanos.

Ejemplo: “42.2K”.

refs

( )

(property) Mapeo entre refs y estructuras de datos de revisión.

CachedRevisionInfo

clase huggingface_hub.CachedRevisionInfo

( commit_hash: strsnapshot_path: Pathsize_on_disk: intfiles: frozensetrefs: frozensetlast_modified: float )

Parámetros

commit_hash (str) — Hash de la revisión (único). Ejemplo: "9338f7b671827df886678df2bdd7cc7b4f36dffd".
snapshot_path (Path) — Ruta al directorio de la revisión en la carpeta snapshots. Contiene la estructura exacta del árbol del repositorio en el Hub.
files — (frozenset[CachedFileInfo]): Conjunto de ~CachedFileInfo que describe todos los archivos contenidos en la instantánea.
refs (frozenset[str]) — Conjunto de refs que apuntan a esta revisión. Si la revisión no tiene refs, se considera desvinculada. Ejemplo: {"main", "2.4.0"} o {"refs/pr/1"}.
size_on_disk (int) — Suma de los tamaños de los archivos blob a los que la revisión hace referencia mediante enlaces simbólicos.
last_modified (float) — Marca de tiempo de la última vez que se creó o modificó la revisión.

Estructura de datos inmutable que contiene información sobre una revisión.

Una revisión corresponde a una carpeta en la carpeta snapshots y se rellena con la estructura de árbol exacta del repositorio en el Hub, pero solo contiene enlaces simbólicos. Una revisión puede estar referenciada por uno o más refs o estar “desconectada” (sin refs).

No se puede determinar correctamente last_accessed en una sola revisión, ya que los archivos blob se comparten entre revisiones.

size_on_disk no es necesariamente la suma de todos los tamaños de archivo debido a posibles archivos duplicados. Además, solo se tienen en cuenta los blobs, no el (despreciable) tamaño de las carpetas y los enlaces simbólicos.

size_on_disk_str

( )

(property) Suma de los tamaños de los archivos blob como una cadena legible por humanos.

Ejemplo: “42.2K”.

nb_files

( )

(property) Número total de archivos en la revisión.

CachedFileInfo

clase huggingface_hub.CachedFileInfo

( file_name: strfile_path: Pathblob_path: Pathsize_on_disk: intblob_last_accessed: floatblob_last_modified: float )

Parámetros

file_name (str) — Nombre del archivo. Ejemplo: config.json.
file_path (Path) — Ruta del archivo en el directorio snapshots. La ruta del archivo es un enlace simbólico que hace referencia a un blob en la carpeta blobs.
blob_path (Path) — Ruta de la entrada de blob local del repositorio a la que hace referencia file_path. La entrada de blob puede ser a su vez un enlace simbólico al almacén de blobs compartido de todo el caché.
size_on_disk (int) — Tamaño del archivo blob en bytes.
blob_last_accessed (float) — Marca de tiempo de la última vez que se accedió al archivo blob (desde cualquier revisión).
blob_last_modified (float) — Marca de tiempo de la última modificación/creación del archivo blob.

Estructura de datos inmutable que contiene información sobre un único archivo en caché.

La fiabilidad de blob_last_accessed y blob_last_modified puede depender del sistema operativo que estés utilizando. Consulta la documentación de Python para más detalles.

size_on_disk_str

( )

(property) Tamaño del archivo blob como una cadena legible por humanos.

Ejemplo: “42.2K”.

CachedIncompleteFileInfo

clase huggingface_hub.CachedIncompleteFileInfo

( file_path: Pathsize_on_disk: int )

Parámetros

file_path (Path) — Ruta del archivo .incomplete en la carpeta blobs.
size_on_disk (int) — Tamaño del archivo descargado parcialmente en bytes.

Estructura de datos inmutable que contiene información sobre una sola descarga incompleta.

Las descargas interrumpidas dejan archivos <cache>/<repo>/blobs/<etag>.incomplete. Estos no forman parte de ninguna revisión confirmada, por lo que scan_cache_dir() los muestra por separado.

DeleteCacheStrategy

clase huggingface_hub.DeleteCacheStrategy

( expected_freed_size: intblobs: frozensetrefs: frozensetrepos: frozensetsnapshots: frozensetfiles: frozenset = frozenset()cache_dir: pathlib.Path | None = None )

Parámetros

expected_freed_size (float) — Tamaño esperado liberado una vez que se ejecuta la estrategia.
blobs (frozenset[Path]) — Conjunto de rutas de archivos blob que se eliminarán.
refs (frozenset[Path]) — Conjunto de rutas de archivos de referencia que se eliminarán.
repos (frozenset[Path]) — Set of entire repo paths to be deleted.
snapshots (frozenset[Path]) — Conjunto de instantáneas que se eliminarán (directorio de enlaces simbólicos).
files (frozenset[Path], opcional) — Conjunto de entradas individuales de instantánea que se eliminarán. Sus blobs solo se eliminarán si están listados en blobs.
cache_dir (Path o None) — Directorio de caché desde el que se calculó la estrategia. Se utiliza para recopilar los blobs compartidos referenciados por los enlaces simbólicos locales del repositorio eliminados por la supresión.

Estructura de datos inmutable que contiene la estrategia para eliminar revisiones o archivos en caché.

Este objeto no está diseñado para instanciarse de forma programática, sino para ser devuelto por delete_revisions() o delete_files(). Consulte la documentación para un ejemplo de uso.

expected_freed_size_str

( )

(property) Tamaño esperado que se liberará, como una cadena legible por humanos.

Ejemplo: “42.2K”.

Excepciones

CorruptedCacheException

clase huggingface_hub.CorruptedCacheException

( )

Excepción para cualquier estructura inesperada en el sistema de caché de Huggingface.

Update on GitHub

←Discusiones y Pull Requests Tarjetas de repositorio y datos de tarjetas de repositorio→