Cómo vaciar de forma segura la caché de Hugging Face

Utiliza los comandos actuales de hf cache para inspeccionar la caché antes de eliminar nada. Elimina un repositorio o revisión conocidos con hf cache rm; usa hf cache prune para las revisiones que ya no tengan referencias. No trates el directorio de caché como un montón de archivos independientes: los snapshots pueden compartir los mismos blobs.

Por qué la eliminación manual entraña riesgos que no son evidentes

La caché del Hub está diseñada para evitar descargar dos veces contenido idéntico. Dentro de la caché hub, un repositorio suele contener refs, snapshots y blobs. Un snapshot presenta una revisión como un directorio utilizable, mientras que sus archivos pueden enlazar al contenido compartido de blobs. Por tanto, puede parecer que dos revisiones contienen el mismo archivo grande de pesos sin que ocupen dos copias completas.

Esa estructura es eficiente, pero convierte «eliminar la carpeta que parezca más grande» en una mala regla. Borrar manualmente un blob activo puede romper más de un snapshot. Eliminar un snapshot puede liberar mucho menos espacio que su tamaño aparente porque otras revisiones aún hacen referencia al mismo contenido.

Mide la caché que utilizas realmente

Localiza primero el directorio de caché de Hugging Face activo. HF_HOME, HF_HUB_CACHE y otras variables relacionadas pueden haberlo movido de su ubicación predeterminada. Después, pide a la CLI que muestre el estado de la caché:

hf cache ls
hf cache ls --revisions

El primer comando enumera los repositorios almacenados en caché; el segundo muestra las revisiones individuales. Utiliza los filtros o la ordenación de la CLI actual cuando la lista sea larga. La decisión que necesitas no es simplemente «¿qué es antiguo?», sino «¿qué repositorio o revisión concretos se pueden volver a obtener y cuáles respaldan el trabajo actual?».

Elimina de forma deliberada un repositorio o una revisión

Cuando sepas que todo un repositorio almacenado en caché es prescindible, pasa su identificador de caché a hf cache rm. La documentación actual utiliza un identificador de repositorio como este:

hf cache rm model/gpt2

Para una limpieza más acotada, selecciona el identificador concreto de revisión que indique hf cache ls --revisions. Lee con atención la vista previa y la confirmación. La CLI puede calcular qué queda sin referencias; una selección del sistema de archivos no puede explicarte esas relaciones.

Poda las revisiones desvinculadas, no tu conjunto de trabajo

hf cache prune selecciona revisiones que ya no tienen referencias. Es la herramienta adecuada para los datos de revisiones obsoletos que quedan cuando cambian las referencias de ramas o etiquetas, pero no promete que desaparezcan todos los modelos antiguos que ya no recuerdas. Ejecútala después de inspeccionar la eliminación propuesta, no como reflejo automático al final de cada sesión.

hf cache prune

Si varios usuarios, contenedores o tareas programadas gestionan la caché, detén primero las descargas activas. Una limpieza realizada mientras otro proceso materializa un snapshot crea una ambigüedad innecesaria, aunque la implementación de la caché esté diseñada para recuperarse.

Comprueba qué queda

1. Ejecuta de nuevo hf cache ls y registra el nuevo tamaño.
2. Utiliza hf cache verify <repo> con un repositorio conservado que te importe.
3. Inicia un flujo de trabajo real que cargue un modelo conservado.
4. Vigila si se produce una descarga nueva: un modelo que vuelve a obtenerse de forma silenciosa no estaba disponible por completo en local.

Volver a descargar no siempre supone un fallo —la caché es una caché—, pero importa si trabajas sin conexión, fijas una revisión concreta o dependes de un archivo de origen que podría desaparecer.

La limpieza de la caché y la conservación a largo plazo resuelven problemas distintos

La caché del Hub está optimizada para reutilizar y volver a obtener datos. No es un registro organizado que explique por qué un modelo, tokenizador, configuración o adaptador forman una familia. Antes de vaciar una revisión difícil de reproducir, identifica la familia completa necesaria para usarla. En un adaptador PEFT, puede incluir un modelo base compatible y su configuración; en un resultado de entrenamiento, puede incluir más que los pesos.

Tensor Archive pertenece al lado de la gestión deliberada. Conserva una familia local terminada, verifica el archivo y demuestra una restauración exacta. Así, la caché puede volver a ser infraestructura desechable en lugar de un museo accidental.

Guías relacionadas

Si la caché actual está simplemente en el disco equivocado, sigue la guía independiente para cambiar el directorio de caché de Hugging Face. Si la biblioteca abarca varios entornos, utiliza la lista de comprobación de conservación antes de decidir qué es solo un estado de caché reemplazable.