Hub Python Library documentation
Comprender la caché
Comprender la caché
huggingface_hub utiliza una caché local basada en archivos para almacenar los archivos individuales descargados del Hub y evitar volver a descargar archivos sin cambios cuando un repositorio se actualiza. Además, hf_xet almacena una caché de fragmentos y datos de preparación para optimizar las cargas (ver Caché de Xet).
Esta guía cubre las herramientas de gestión de caché específicas de Python que proporciona
huggingface_hub. Para una descripción general independiente del lenguaje sobre cómo funciona el sistema de caché de Hugging Face Hub, consulte la documentación de Hub sobre la caché local.
Caché basada en archivos
El sistema de caché del Hugging Face Hub está diseñado para ser la caché central compartida entre las bibliotecas que dependen del Hub. Se actualizó en la v0.8.0 para evitar la descarga repetida de los mismos archivos entre revisiones.
El sistema de caché está diseñado de la siguiente manera:
<CACHE_DIR>
├─ <MODELS>
├─ <DATASETS>
├─ <SPACES>
├─ <KERNELS>El valor predeterminado de <CACHE_DIR> es ~/.cache/huggingface/hub. Sin embargo, se puede personalizar con el argumento cache_dir en todos los métodos, o especificando la variable de entorno HF_HOME o HF_HUB_CACHE.
Los modelos, conjuntos de datos, espacios y kernels comparten una raíz común. Cada uno de estos repositorios contiene el tipo de repositorio, el espacio de nombres (organización o nombre de usuario) si existe y el nombre del repositorio:
<CACHE_DIR>
├─ models--julien-c--EsperBERTo-small
├─ models--lysandrejik--arxiv-nlp
├─ models--bert-base-cased
├─ datasets--glue
├─ datasets--huggingface--DataMeasurementsFiles
├─ spaces--dalle-mini--dalle-miniEs en estas carpetas donde ahora se descargarán todos los archivos desde el Hub. La caché garantiza que un archivo no se descargue dos veces si ya existe y no se ha actualizado; pero si se actualizó y estás solicitando el archivo más reciente, se descargará el archivo más reciente (mientras se mantiene el archivo anterior intacto por si lo necesitas de nuevo).
Para lograr esto, todas las carpetas contienen el mismo esqueleto:
<CACHE_DIR>
├─ datasets--glue
│ ├─ refs
│ ├─ blobs
│ ├─ snapshots
│ ├─ trees
...Cada carpeta está diseñada para contener lo siguiente:
Referencias
La carpeta refs contiene archivos que indican la última revisión de la referencia dada. Por ejemplo, si hemos obtenido previamente un archivo de la rama main de un repositorio, la carpeta refs contendrá un archivo llamado main, que a su vez contendrá el identificador del commit de la cabecera actual.
Si el último commit de main tiene aaaaaa como identificador, entonces contendrá aaaaaa.
Si esa misma rama se actualiza con un nuevo commit que tiene bbbbbb como identificador, entonces
volver a descargar un archivo de esa referencia actualizará el archivo refs/main para que contenga bbbbbb.
Blobs
La carpeta blobs contiene los archivos reales que hemos descargado. El nombre de cada archivo es su hash.
Instantáneas
La carpeta snapshots contiene enlaces simbólicos a los blobs mencionados anteriormente. Está compuesta por varias carpetas:
una por cada revisión conocida.
En la explicación anterior, inicialmente obtuvimos un archivo de la revisión aaaaaa, antes de obtener un archivo de la revisión bbbbbb. En esta situación, ahora tendríamos dos carpetas en la carpeta snapshots: aaaaaa y bbbbbb.
En cada una de estas carpetas, hay enlaces simbólicos con los nombres de los archivos que hemos descargado. Por ejemplo, si hubiéramos descargado el archivo README.md en la revisión aaaaaa, tendríamos la siguiente ruta:
<CACHE_DIR>/<REPO_NAME>/snapshots/aaaaaa/README.mdEse archivo README.md es en realidad un enlace simbólico que apunta al blob que contiene el hash del archivo.
Al crear el esqueleto de esta manera, abrimos el mecanismo para el intercambio de archivos: si el mismo archivo se había obtenido en la revisión bbbbbb, tendría el mismo hash y no sería necesario volver a descargarlo.
Árboles
La carpeta trees almacena en caché la lista de archivos que contiene un repositorio en un commit determinado. Un commit es inmutable, por lo que su lista de archivos nunca cambia. Esto significa que la lista puede almacenarse en caché de forma permanente sin necesidad de volver a verificarla contra el Hub.
Cada lista en caché se nombra según un hash de commit y se almacena como un archivo JSON, por ejemplo trees/aaaaaa.json. Para cada archivo del repositorio en ese commit, registra lo necesario para descargar el archivo: su ruta, su tamaño y su hash. Esta es la misma información que el Hub devolvería de otro modo, pero normalmente cuesta una llamada de red por archivo para obtenerla.
Esta caché se escribe mediante snapshot_download(). La primera vez que descargas un commit, la lista de archivos se obtiene una vez y se guarda aquí. La siguiente vez que descargas el mismo commit, la lista se lee desde el disco en lugar de volver a obtenerla. Como resultado, volver a ejecutar una descarga cuando todo ya está en caché tiene un coste de una sola llamada de red: la necesaria para resolver el nombre de la rama o etiqueta en un hash de commit.
Tanto snapshot_download() como hf_hub_download() leen esta caché para evitar llamadas de red. Cuando descargas un archivo con un hash de commit como revisión (esto es exactamente lo que snapshot_download() hace internamente para cada archivo), los metadatos de la descarga se leen de la lista de archivos en caché y se omite la llamada de red por archivo. Esto significa que una hf_hub_download() para un solo archivo también se beneficia de una lista de archivos que una snapshot_download() anterior guardó para el mismo commit.
Dado que la lista de archivos en caché describe exactamente lo que debe contener un commit, snapshot_download() también puede indicar si un snapshot local está completo. Si el Hub no se puede alcanzar (estás sin conexión, la conexión falla o pasaste local_files_only=True) y faltan algunos archivos esperados en el snapshot local, snapshot_download() lanza IncompleteSnapshotError en lugar de devolver una carpeta parcial. Antes de esto, un snapshot incompleto se devolvía en silencio, lo que podía dejarte trabajando con archivos faltantes sin saberlo. Los archivos excluidos por allow_patterns o ignore_patterns no se cuentan como faltantes. La excepción expone la ruta al snapshot incompleto a través de su atributo snapshot_path, por lo que aún puedes localizar los archivos parcialmente en caché si es necesario.
.no_exist (avanzado)
Además de las carpetas blobs, refs y snapshots, es posible que también encuentres una carpeta .no_exist en tu caché. Esta carpeta lleva un registro de los archivos que has intentado descargar una vez pero que no existen en el Hub. Su estructura es la misma que la de la carpeta snapshots, con 1 subcarpeta por revisión conocida:
<CACHE_DIR>/<REPO_NAME>/.no_exist/aaaaaa/config_that_does_not_exist.jsonA diferencia de la carpeta snapshots, los archivos son archivos vacíos simples (sin enlaces simbólicos). En este ejemplo,
el archivo "config_that_does_not_exist.json" no existe en el Hub para la revisión "aaaaaa".
Como solo almacena archivos vacíos, esta carpeta es despreciable en términos de uso de disco.
Ahora bien, es posible que se pregunte por qué es relevante esta información.
En algunos casos, un framework intenta cargar archivos opcionales de un modelo. Guardar la inexistencia
de archivos opcionales hace que la carga de un modelo sea más rápida, ya que se ahorra 1 llamada HTTP por cada archivo opcional posible.
Este es, por ejemplo, el caso en transformers, donde cada tokenizer puede admitir archivos adicionales.
La primera vez que carga el tokenizer en su máquina, se cachea qué archivos opcionales existen (y
cuáles no) para que el tiempo de carga sea más rápido en las siguientes inicializaciones.
Para comprobar si un archivo está en caché localmente (sin realizar ninguna solicitud HTTP), puede usar el helper try_to_load_from_cache(). Devolverá la ruta del archivo (si existe y está en caché), el objeto _CACHED_NO_EXIST (si la inexistencia está en caché) o None (si no lo sabemos).
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
...En la práctica
En la práctica, su caché debería tener el siguiente aspecto:
[ 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
└── [ 96] trees
├── [ 521] 2439f60ef33a0d46d85da5001d52aeda5b00ce9f.json
└── [ 521] bbc77c8132af1cc5cf678da3f1ddf2de43606d48.jsonCACHEDIR.TAG
huggingface_hub crea automáticamente un archivo CACHEDIR.TAG dentro del directorio de caché. Esta etiqueta sigue el Cache Directory Tagging Standard e indica a las herramientas de copia de seguridad (p. ej. Borg, restic, rsync) que el directorio contiene datos de caché que pueden volver a descargarse y que pueden excluirse de las copias de seguridad de forma segura.
Limitaciones
Para contar con un sistema de caché eficiente, huggingface-hub utiliza enlaces simbólicos. Sin embargo, los enlaces simbólicos no son compatibles con todos los equipos. Esta es una limitación conocida, especialmente en Windows. En ese caso, huggingface_hub no utiliza el directorio blobs/, sino que almacena los archivos directamente en el directorio snapshots/. Este mecanismo alternativo permite a los usuarios descargar y almacenar en caché archivos del Hub de la misma manera. Las herramientas para inspeccionar y eliminar la caché (ver más abajo) también son compatibles. No obstante, el sistema de caché es menos eficiente, ya que un archivo único podría descargarse varias veces si se descargan múltiples revisiones del mismo repositorio.
Si deseas aprovechar el sistema de caché basado en enlaces simbólicos en una máquina con Windows, debes activar el modo de desarrollador o ejecutar Python como administrador.
Si desea usar proactivamente el modo de caché sin enlaces simbólicos (p. ej. en un sistema de archivos compartido que no maneja bien los enlaces simbólicos), puede establecer la variable de entorno HF_HUB_DISABLE_SYMLINKS en 1. Los archivos se copiarán directamente en snapshots/ en lugar de enlazar simbólicamente a blobs/.
Cuando los enlaces simbólicos no son compatibles, se muestra un mensaje de advertencia al usuario para alertarle de que está utilizando una versión degradada del sistema de caché. Esta advertencia se puede desactivar estableciendo la variable de entorno HF_HUB_DISABLE_SYMLINKS_WARNING en true.
Blobs compartidos entre repositorios
Por defecto, los archivos Xet también se deduplican entre repositorios. Un archivo Xet descargado a través de hf_xet se almacena una vez en <CACHE_DIR>/blobs/<prefix>/<xet_hash>, y la entrada blobs/<etag> del repositorio es un enlace simbólico relativo a él. Cuando otro repositorio necesita el mismo archivo, recibe un enlace simbólico en lugar de una descarga: no se transfieren bytes y no se usa espacio adicional. El diseño de la instantánea no cambia. Un archivo de marcador identifica el almacén, por lo que un directorio blobs que no fue creado por huggingface_hub nunca se modifica.
Cada archivo compartido tiene un manifiesto <xet_hash>.refs que lista los blobs del repositorio que lo utilizan. hf cache rm lo lee para comprobar solo los archivos compartidos afectados por una eliminación, y hf cache prune elimina los archivos compartidos que ningún repositorio en caché utiliza ya. El manifiesto es solo una pista: cada entrada se comprueba contra el sistema de archivos, y un archivo con metadatos faltantes o no legibles se conserva. La limpieza prioriza dejar datos recuperables antes que romper una entrada de caché válida.
Los tamaños por repositorio se mantienen lógicos, por lo que un archivo compartido se cuenta para cada repositorio que lo utiliza. El size_on_disk de toda la caché es físico: cada archivo compartido se cuenta una sola vez, incluidos los archivos que ningún repositorio utiliza ya.
Los clientes más antiguos (huggingface_hub, huggingface.js, hf-hub, llama.cpp y cualquier otro que siga enlaces simbólicos) siguen leyendo y descargando con normalidad, en las mismas carpetas de repositorio. Dos limitaciones:
huggingface_hub<=1.31deja los archivos compartidos de un repositorio eliminado en el almacén, dondehf cache lslos marca yhf cache prunelos elimina. Las herramientas de eliminación de caché de otros clientes pueden, en cambio, eliminar un archivo compartido que aún se utiliza en otros repositorios; los archivos afectados se vuelven a descargar en el siguiente uso. Utilice una versión actualizada dehuggingface_hubparahf cache rm,hf cache pruney la eliminación programática.- Sus analizadores de caché pueden informar que el directorio
blobsde nivel superior es una entrada desconocida.
El almacén requiere el diseño de caché basado en enlaces simbólicos y se desactiva con HF_HUB_DISABLE_XET=1. Cualquier fallo al compartir un archivo, como un sistema de archivos no compatible, un error de permisos o un directorio blobs existente sin marcar, recurre silenciosamente al almacenamiento local regular del repositorio. Establezca HF_HUB_DISABLE_SHARED_BLOBS=1 para desactivarlo por completo.
Fijar una revisión (avanzado)
Si estás integrando el Hub en una biblioteca de ML, una sola llamada a snapshot_download() sigue siendo el enfoque recomendado: resuelve la revisión una vez, descarga todo en paralelo y almacena en caché la lista de archivos. Lo que sigue solo es útil para bibliotecas complejas que descargan y cargan muchos componentes por separado (config, pesos, tokenizer, processor, adapters, …) y no pueden usar una sola llamada.
Cuando una biblioteca descarga varios archivos uno por uno, cada llamada debe resolver revision="main" en un hash de commit de nuevo. Esto cuesta una llamada HTTP por archivo y, peor aún, dos llamadas realizadas a pocos segundos de distancia pueden apuntar a dos commits diferentes si el repositorio se actualiza en el intervalo.
HfApi.resolve_revision() resuelve la revisión una vez y devuelve un ResolvedRevision:
>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')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 lo que el usuario solicitó inicialmente ("main" en este caso, de ahí los mensajes de error legibles), mientras que .resolved contiene el hash del commit:
>>> revision == "main"
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'Los helpers de descarga (hf_hub_download(), snapshot_download(), get_cached_repo_tree()) detectan un ResolvedRevision y usan el hash del commit directamente. Se garantiza que cada archivo proviene del mismo commit y, una vez que los archivos están en caché, no se necesita ninguna llamada HTTP:
>>> from huggingface_hub import hf_hub_download
>>> config = hf_hub_download("openai-community/gpt2", "config.json", revision=revision)
>>> weights = hf_hub_download("openai-community/gpt2", "model.safetensors", revision=revision)El mapeo de revision -> commit hash también se escribe en la carpeta refs/ de la caché (ver Refs). Esto significa que si más adelante no se puede acceder al Hub (modo sin conexión, error de conexión, tiempo de espera agotado, caída del Hub), HfApi.resolve_revision() recurre de forma transparente al valor en caché. Si tampoco hay nada en caché, se lanza un RevisionResolutionError.
Un hash de commit solo tiene significado para el repositorio contra el que se resolvió, y las utilidades de descarga lo usan tal cual. Por lo tanto, un ResolvedRevision solo debe pasarse al repositorio para el que se resolvió. Si una biblioteca también descarga de otro repositorio (un modelo base, un adaptador, un componente que vive en su propio repositorio, …), necesita una revisión resuelta para ese repositorio. Simplemente pasa el ResolvedRevision de vuelta a HfApi.resolve_revision(): recuerda a qué repositorio pertenece y resuelve de nuevo la revisión solicitada inicialmente ("main" aquí) para el nuevo repositorio.
>>> other_revision = resolve_revision("openai-community/gpt2-medium", revision=revision) # resolves "main" again
>>> other_revision.resolved
'6dcaa7a952f72f9298047fd5137cd6e4f05f41da'
>>> config = hf_hub_download("openai-community/gpt2-medium", "config.json", revision=other_revision)Caché de Xet
Para ofrecer cargas más eficientes, hf_xet añade un directorio xet a la caché existente de huggingface_hub. Almacena fragmentos (una estructura de datos que asigna archivos a bloques) y datos de preparación utilizados para la deduplicación y la reanudación de las cargas. Para obtener más información sobre el sistema de almacenamiento Xet, consulte esta sección.
hf_xet ya no utiliza una caché local de fragmentos para las descargas. Establecer HF_XET_CHUNK_CACHE_SIZE_BYTES no la habilita. Los archivos descargados siguen almacenándose en la caché basada en archivos.
El directorio xet, situado por defecto en ~/.cache/huggingface/xet, se puede configurar con HF_XET_CACHE. Tiene la siguiente estructura:
<CACHE_DIR> ├─ xet │ ├─ environment_identifier │ │ ├─ shard-cache │ │ ├─ staging
El directorio environment_identifier es una cadena codificada (en tu máquina puede aparecer como https___cas_serv-tGqkUaZf_CBPHQ6h). Se utiliza durante el desarrollo, lo que permite que existan simultáneamente versiones locales y de producción de la caché. También se emplea al descargar de repositorios que se encuentran en diferentes regiones de almacenamiento. Es posible que veas varias entradas de este tipo en el directorio xet, cada una correspondiente a un entorno diferente, pero su estructura interna es la misma.
Los directorios internos cumplen las siguientes funciones:
shard-cachecontiene fragmentos en caché que se utilizan en la ruta de carga.staginges un espacio de trabajo diseñado para admitir cargas reanudables.
Estas se documentan a continuación.
La caché de fragmentos y los datos de preparación los gestiona hf_xet como una capa de optimización para las cargas. Para gestionar los archivos descargados, utiliza las APIs de caché basadas en archivos de huggingface_hub.
shard-cache
Esta caché se utiliza al subir contenido al Hub. El directorio es plano y consta únicamente de archivos de fragmento, cada uno de los cuales utiliza un ID como nombre del fragmento.
<CACHE_DIR> ├─ xet │ ├─ environment_identifier │ │ ├─ shard-cache │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb │ │ │ ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb
El shard-cache contiene fragmentos que son:
- Generado localmente y subido correctamente al CAS
- Descargado de CAS como parte del algoritmo global de deduplicación
Los shards proporcionan un mapeo entre archivos y chunks. Durante las cargas, cada archivo se divide en chunks y se guarda el hash de cada chunk. A continuación, se consulta cada shard en la caché. Si un shard contiene un hash de chunk que está presente en el archivo local que se está cargando, ese chunk puede descartarse, ya que ya está almacenado en CAS.
Todos los fragmentos tienen una fecha de caducidad de 3 a 4 semanas a partir de su descarga. Los fragmentos caducados no se cargan durante la carga y se eliminan una semana después de su caducidad.
staging
Cuando una carga se interrumpe antes de que el nuevo contenido se haya confirmado en el repositorio, será necesario reanudar la transferencia del archivo. Sin embargo, es posible que algunos fragmentos se hayan subido correctamente antes de la interrupción.
Para que no tengas que reiniciar desde el principio, el directorio staging actúa como un espacio de trabajo durante las cargas, almacenando los metadatos de los fragmentos cargados con éxito. El directorio staging tiene la siguiente estructura:
<CACHE_DIR>
├─ xet
│ ├─ environment_identifier
│ │ ├─ staging
│ │ │ ├─ shard-session
│ │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│ │ │ │ ├─ xorb-metadata
│ │ │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdbA medida que se procesan los archivos y se suben los fragmentos con éxito, sus metadatos se almacenan en xorb-metadata como un shard. Al reanudar una sesión de subida, cada archivo se procesa de nuevo y se consultan los shards de este directorio. Se omite cualquier contenido que ya se haya subido con éxito y se sube cualquier contenido nuevo (y se guarda su metadatos).
Mientras tanto, shard-session almacena la información de archivos y fragmentos para los archivos procesados. Al completar correctamente una carga, el contenido de estos fragmentos se mueve al shard-cache más persistente.
Limites y limitaciones
El shard-cache tiene un límite blando de 16 GB, configurable a través de la variable de entorno HF_XET_SHARD_CACHE_SIZE_LIMIT. No existe una API de alto nivel para gestionar esta caché.
La caché de fragmentos y los datos de preparación se utilizan para optimizar las cargas. Para interactuar con los propios recursos, se recomienda que utilices las APIs del sistema de caché de huggingface_hub.
Si necesitas recuperar el espacio utilizado por Xet o necesitas depurar posibles problemas relacionados con la caché, simplemente elimina por completo la caché de xet ejecutando rm -rf ~/<cache_dir>/xet, donde <cache_dir> es la ubicación de tu caché de Hugging Face, normalmente ~/.cache/huggingface
Ejemplo de árbol de directorios de la caché de xet:
<CACHE_DIR> ├─ xet │ ├─ environment_identifier │ │ ├─ shard-cache │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb │ │ │ ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb │ │ ├─ staging │ │ │ ├─ shard-session │ │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ │ ├─ xorb-metadata │ │ │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
Para obtener más información sobre Xet Storage, consulte esta sección.
Caché de recursos
Además de cachear archivos del Hub, las bibliotecas de nivel inferior a menudo necesitan cachear otros archivos relacionados con HF que no son gestionados directamente por huggingface_hub (por ejemplo: archivos descargados de GitHub, datos preprocesados, registros, etc.). Para cachear esos archivos, llamados assets, se puede usar cached_assets_path(). Esta pequeña función auxiliar genera rutas en la caché de HF de manera unificada, basándose en el nombre de la biblioteca que lo solicita y, opcionalmente, en un espacio de nombres y un nombre de subcarpeta. El objetivo es permitir que cada biblioteca de nivel inferior gestione sus assets a su manera (por ejemplo, sin reglas sobre la estructura), siempre que se mantenga en la carpeta de assets correcta. Esas bibliotecas pueden aprovechar entonces las herramientas de huggingface_hub para gestionar la caché, en particular para escanear y eliminar partes de los assets desde un comando de CLI.
from huggingface_hub import cached_assets_path
assets_path = cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download")
something_path = assets_path / "something.json" # Do anything you like in your assets folder !cached_assets_path() es la forma recomendada de almacenar los recursos, pero no es obligatoria. Si tu biblioteca ya utiliza su propia caché, ¡no dudes en usarla!
Activos en la práctica
En la práctica, su caché de activos debería tener el siguiente aspecto:
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/
└── (...)Gestiona tu caché basada en archivos
Inspecciona tu caché
Por el momento, los archivos en caché nunca se eliminan de tu directorio local: cuando descargas una nueva revisión de una rama, los archivos anteriores se conservan por si los necesitas de nuevo. Por lo tanto, puede ser útil inspeccionar tu directorio de caché para saber qué repositorios y revisiones ocupan más espacio en disco. huggingface_hub ofrece utilidades que puedes usar desde la CLI hf o desde Python.
Inspeccionar la caché desde la terminal
Ejecuta hf cache ls para explorar lo que se almacena localmente. Por defecto, el comando agrega la información por repositorio:
➜ hf cache ls ID SIZE LAST_ACCESSED LAST_MODIFIED REFS ------------------------------------ ------- ------------- ------------- ------------------- dataset/glue 116.3K 4 days ago 4 days ago 2.4.0 main 1.17.0 dataset/google/fleurs 64.9M 1 week ago 1 week ago main refs/pr/1 model/Jean-Baptiste/camembert-ner 441.0M 2 weeks ago 16 hours ago main model/bert-base-cased 1.9G 1 week ago 2 years ago model/t5-base 10.1K 3 months ago 3 months ago main model/t5-small 970.7M 3 days ago 3 days ago main refs/pr/1 Found 6 repo(s) for a total of 12 revision(s) and 3.4G on disk.
Añada --revisions para listar cada instantánea en caché y encadene filtros para centrarse en lo que importa. Los filtros comprenden tamaños y duraciones legibles para humanos, por lo que expresiones como size>1GB o accessed>30d funcionan sin configuración adicional:
➜ hf cache ls --revisions --filter "size>1GB" --filter "accessed>30d" ID REVISION SIZE LAST_MODIFIED REFS ------------------------------------ ------------------ ------- ------------- ------------------- model/bert-base-cased 6d1d7a1a2a6cf4c2 1.9G 2 years ago model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main Found 2 repo(s) for a total of 2 revision(s) and 3.0G on disk.
¿Necesita una salida apta para máquinas? Use --format json para obtener objetos estructurados o --format csv para hojas de cálculo. Alternativamente, --quiet imprime solo identificadores (uno por línea) para que pueda enviarlos a otras herramientas mediante tubería. Use --sort para ordenar las entradas por accessed, modified, name o size (añada :asc o :desc para controlar el orden) y --limit para limitar los resultados a las N primeras entradas. Combine estas opciones con --cache-dir cuando necesite inspeccionar una caché almacenada fuera de HF_HOME.
Filtrar con herramientas comunes de shell
La salida tabular significa que puedes seguir utilizando las herramientas que ya conoces. Por ejemplo, el fragmento de código siguiente encuentra todas las revisiones en caché relacionadas con t5-small:
➜ eval "hf cache ls --revisions" | grep "t5-small" model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main model/t5-small 8f3ad1c90fed7a62 820.1M 2 weeks ago refs/pr/1
Inspeccionar la caché desde Python
Para un uso más avanzado, utilice scan_cache_dir(), que es la utilidad de python que llama la herramienta de CLI.
Puede utilizarlo para obtener un informe detallado estructurado en torno a 4 dataclasses:
- HFCacheInfo: informe completo devuelto por scan_cache_dir()
- CachedRepoInfo: información sobre un repositorio en caché
- CachedRevisionInfo: información sobre una revisión en caché (p. ej., “snapshot”) dentro de un repositorio
- CachedFileInfo: información sobre un archivo en caché en una instantánea
Aquí hay un ejemplo de uso sencillo. Consulte la referencia para más detalles.
>>> 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,
last_accessed=1662971707.3567169,
last_modified=1662971107.3567169,
revisions=frozenset({
CachedRevisionInfo(
commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5',
size_on_disk=970726339,
snapshot_path=PosixPath(...),
# No `last_accessed` as blobs are shared among revisions
last_modified=1662971107.3567169,
files=frozenset({
CachedFileInfo(
file_name='config.json',
size_on_disk=1197
file_path=PosixPath(...),
blob_path=PosixPath(...),
blob_last_accessed=1662971707.3567169,
blob_last_modified=1662971107.3567169,
),
CachedFileInfo(...),
...
}),
),
CachedRevisionInfo(...),
...
}),
),
CachedRepoInfo(...),
...
}),
warnings=[
CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."),
CorruptedCacheException(...),
...
],
)Verifica tu caché
huggingface_hub puede verificar que los archivos en caché coincidan con las sumas de verificación del Hub. Utilice la CLI hf cache verify para validar la consistencia de los archivos de una revisión específica de un repositorio específico:
>>> hf cache verify meta-llama/Llama-3.2-1B-Instruct
✅ Verified 13 file(s) for 'meta-llama/Llama-3.2-1B-Instruct' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6
All checksums match.Verificar una revisión específica en caché:
>>> hf cache verify meta-llama/Llama-3.1-8B-Instruct --revision 0e9e39f249a16976918f6564b8830bc894c89659Consulte la referencia de la CLI
hf cache verifypara obtener más detalles sobre el uso y una lista completa de opciones.
Limpia tu caché
Escanear la caché es interesante, pero lo que normalmente se quiere hacer a continuación es eliminar algunas partes para liberar espacio en el disco. Esto es posible usando los comandos de CLI hf cache rm y hf cache prune. También se pueden usar programáticamente los helpers delete_revisions() y delete_files() del objeto HFCacheInfo que se devuelve al escanear la caché.
Estrategia de eliminación
Para eliminar parte de la caché, debe pasar una lista de revisiones a eliminar. La herramienta definirá una estrategia para liberar espacio en función de esta lista. Devuelve un objeto DeleteCacheStrategy que describe qué archivos y carpetas se eliminarán. El DeleteCacheStrategy le permite saber cuánta espacio se espera liberar. Una vez que esté de acuerdo con la eliminación, debe ejecutarla para que la eliminación sea efectiva. Para evitar discrepancias, no puede editar un objeto de estrategia manualmente.
La estrategia para eliminar revisiones es la siguiente:
- se elimina la carpeta
snapshotque contiene los enlaces simbólicos de la revisión. - Los archivos blobs que solo son referenciados por revisiones que se van a eliminar también se eliminan.
- si una revisión está vinculada a uno o más
refs, las referencias se eliminan. - si se eliminan todas las revisiones de un repositorio, se elimina todo el repositorio en caché.
Eliminar archivos individuales con delete_files() sigue la misma lógica: se eliminan las entradas de la instantánea y sus blobs solo si ningún otro archivo en caché los referencia. Las referencias y las carpetas de instantáneas se conservan.
Los hashes de revisión son únicos en todos los repositorios. Por lo tanto,
hf cache rmacepta un identificador de repositorio (por ejemplo,model/bert-base-uncased) o un hash de revisión sin más; al pasar un hash, no es necesario especificar el repositorio por separado.
Si no se encuentra una revisión en la caché, se ignorará silenciosamente. Además, si un archivo o carpeta no se puede encontrar al intentar eliminarlo, se registrará una advertencia pero no se lanzará un error. La eliminación continúa para otras rutas contenidas en el objeto DeleteCacheStrategy.
Limpiar la caché desde la terminal
Use hf cache rm para eliminar de forma permanente repositorios o revisiones de su caché. Pase
uno o más identificadores de repositorio (por ejemplo, model/bert-base-uncased) o hashes de revisión:
➜ hf cache rm model/bert-base-cased About to delete 1 repo(s) totalling 1.9G. - model/bert-base-cased (entire repo) Proceed with deletion? [y/N]: y Deleted 1 repo(s) and 1 revision(s); freed 1.9G.
También puede usar hf cache rm en combinación con hf cache ls --quiet para eliminar en lote las entradas identificadas por un filtro:
>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
- model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
- model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.Mezcla repositorios y revisiones en la misma llamada. Añade --dry-run para previsualizar el impacto,
o --yes para omitir el aviso de confirmación al usar scripts:
➜ hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
- model/t5-small:
8f3ad1c [main] 1.1G
Dry run: no files were deleted.Para eliminar un archivo individual en lugar de un repositorio completo, por ejemplo una cuantización GGUF,
pasa un URI de archivo hf://. El archivo se elimina de todas las revisiones en caché del repositorio, y
su blob se elimina solo si ningún otro archivo en caché lo referencia. La revisión sigue
siendo utilizable, y un archivo eliminado se vuelve a descargar la próxima vez que se necesite. Las rutas deben coincidir
exactamente: no se admiten carpetas ni patrones glob.
➜ hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run About to delete 1 file(s) totalling 16.5G. - model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf Dry run: no files were deleted.
Al trabajar fuera de la ubicación de caché predeterminada, combine el comando con --cache-dir PATH.
Para limpiar la basura de la caché en bloque, ejecute hf cache prune. Elimina automáticamente las revisiones que ya no están referenciadas por una rama o etiqueta, los archivos .incomplete residuales de descargas interrumpidas y los blobs compartidos que ningún repositorio en caché referencia ya más:
➜ hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
- model/t5-small:
1c610f6b [refs/pr/1] 820.1M
d4ec9b72 [(detached)] 640.5M
- dataset/google/fleurs:
2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.Los archivos .incomplete son blobs parciales que quedan cuando una descarga se interrumpe. No los rastrea el escaneo basado en revisiones, por lo que hf cache ls solo los marca con una pista (Found X incomplete download(s) ...), mientras que hf cache prune es el comando que realmente los elimina. hf cache rm nunca los toca, excepto cuando elimina un repositorio completo.
Ambos comandos admiten --dry-run, --yes y --cache-dir, por lo que puedes previsualizar, automatizar y dirigirte a directorios de caché alternativos según sea necesario.
Limpiar la caché desde Python
Para mayor flexibilidad, también puedes usar el método delete_revisions() de forma programática. Aquí tienes un ejemplo sencillo. Consulta la referencia para más detalles.
>>> from huggingface_hub import scan_cache_dir
>>> delete_strategy = scan_cache_dir().delete_revisions(
... "81fd1d6e7847c99f5862c9fb81387956d99ec7aa"
... "e2983b237dccf3ab4937c97fa717319a9ca1a96d",
... "6c0e6080953db56375760c0471a8c5f2929baf11",
... )
>>> print("Will free " + delete_strategy.expected_freed_size_str)
Will free 8.6G
>>> delete_strategy.execute()