Cache Hugging Face sous Windows : inspecter, nettoyer et déplacer

Les téléchargements Hugging Face peuvent remplir un disque Windows à cause de plusieurs révisions de modèles, de jeux de données et de téléchargements interrompus. Commencez par les outils de cache de l'environnement qui les a téléchargés. Supprimer un dossier blobs arbitraire peut endommager des révisions qui partagent encore ces fichiers, tandis que supprimer tout HF_HOME peut aussi effacer l'état d'authentification.

Trouver le cache réellement utilisé par votre application

Le cache Hub habituel est %USERPROFILE%\.cache\huggingface\hub, mais une application peut utiliser un autre compte, une variable d'environnement ou un répertoire de cache explicite. La référence des variables d'environnement distingue HF_HOME, HF_HUB_CACHE et HF_XET_CACHE. HF_HOME est plus large que le cache de modèles et inclut le jeton d'authentification stocké.

Ouvrez le terminal ou l'environnement Python utilisé par l'application d'IA et inspectez sa commande installée :

hf cache --help
hf cache ls
hf cache ls --revisions

Ce sont des commandes d'inventaire. Si hf ou une sous-commande est indisponible, vérifiez la version de huggingface_hub dans cet environnement et la procédure de mise à niveau prise en charge par l'outil. Ne mettez pas à niveau une installation Python globale sans rapport en supposant que cela modifie l'environnement privé de l'application.

Pour un cache Hub configuré ailleurs, indiquez le chemin réel avec --cache-dir. Une liste issue de l'emplacement par défaut ne prouve pas que l'emplacement personnalisé plus volumineux est vide.

Vérifiez la commande et le chemin avant de faire confiance au total

Dans PowerShell, ces vérifications indiquent quel exécutable est appelé et les remplacements de chemin du processus en cours. Elles n'affichent pas le jeton d'authentification :

Get-Command hf | Select-Object Source
$env:HF_HOME
$env:HF_HUB_CACHE
$env:HF_XET_CACHE

Une ligne vide signifie que cette variable n'est pas définie dans ce processus PowerShell. Cela ne prouve pas qu'un lanceur de bureau, un environnement virtuel ou un service n'utilise aucun remplacement. Comparez ces relevés avec l'application qui a effectué le téléchargement, surtout lorsque plusieurs installations de Python sont présentes.

Pour un exemple de cache personnalisé, utilisez son chemin explicite à la fois dans l'inventaire et dans l'aperçu :

hf cache ls --cache-dir "D:\AI\huggingface\hub" --revisions
hf cache rm model/OWNER/REPOSITORY --cache-dir "D:\AI\huggingface\hub" --dry-run

Remplacez le chemin et l'ID de dépôt par les valeurs trouvées sur le PC. Si la commande installée rejette une option, arrêtez-vous et consultez son aide. Ne transformez pas un échec de syntaxe en suppression manuelle de dossier. Une liste de zéro entrée à un chemin nouvellement saisi ne prouve pas non plus que le cache réel est vide.

Comprendre pourquoi plusieurs révisions peuvent coûter plus cher sous Windows

L'explication du cache de Hugging Face décrit des blobs partagés et des instantanés de révision. Sous Windows sans prise en charge des liens symboliques, les fichiers peuvent être stockés directement dans les instantanés, si bien qu'un même fichier peut occuper de l'espace plusieurs fois selon les révisions.

Le mode développeur peut activer le comportement plus efficace des liens symboliques lorsque la stratégie l'autorise. Masquer l'avertissement sur les liens symboliques n'active pas les liens symboliques et ne déduplique pas rétroactivement les anciens téléchargements. N'exécutez pas toute une application d'IA en tant qu'administrateur uniquement pour faire taire ce message.

Distinguez aussi le cache Hub des fichiers de modèles copiés dans le dossier propre à une application. Une commande de cache n'inventorie pas tous les fichiers .safetensors ou GGUF présents sur le PC.

Évitez de compter deux fois les fichiers de modèle partagés

La documentation actuelle du cache décrit un partage non seulement entre révisions, mais aussi entre dépôts pour les téléchargements Xet éligibles. La taille signalée pour un dépôt peut être logique, tandis que la taille physique à l'échelle du cache compte les fichiers partagés une seule fois. Additionner la taille de chaque dépôt peut donc surestimer l'espace que leur suppression libérerait.

Cela compte lorsque deux noms de modèle semblent de taille égale. Ils peuvent contenir des poids différents, des fichiers partagés ou des copies distinctes, selon la méthode de téléchargement et le système de fichiers. Laissez l'outil de cache compatible calculer un plan de suppression au lieu de supposer que chaque gigaoctet listé est indépendant.

La même documentation avertit que les anciens clients ne gèrent pas tous correctement le nouveau stockage partagé. Si le cache a été créé par une bibliothèque plus récente que l'outil que vous êtes sur le point d'utiliser pour la suppression, vérifiez la version prise en charge par l'application avant le nettoyage. Conservez l'environnement existant ou utilisez délibérément un outil compatible et maintenu ; ne mettez pas à jour à l'aveugle les dépendances épinglées d'une application.

Le cache Hub n'est qu'un emplacement. Les données Xet, les sorties de traitement de jeux de données et les fichiers explicitement téléchargés dans un répertoire de modèle local peuvent se trouver ailleurs. Si l'aperçu Hub ne représente qu'une petite partie de l'utilisation du disque, identifiez ces autres responsables plutôt que de rendre la suppression Hub plus agressive.

Prévisualiser la suppression d'un dépôt connu

Arrêtez les téléchargements, l'entraînement et l'inférence qui utilisent le cache cible. Identifiez un dépôt dont vous n'avez plus besoin et confirmez que sa révision exacte est de nouveau disponible si la récupération compte. Un accès restreint, des fichiers supprimés en amont et un usage hors ligne peuvent rendre difficile le remplacement d'un modèle nominalement téléchargeable.

Le guide CLI actuel prend en charge une prévisualisation :

hf cache rm model/OWNER/REPOSITORY --dry-run

Remplacez model/OWNER/REPOSITORY par l'ID exact issu de la liste. Lisez les révisions concernées et la taille. Seulement après cet examen, exécutez la même commande sans --dry-run et répondez à sa confirmation. Il s'agit d'une suppression, pas d'un déplacement vers la Corbeille.

Pour nettoyer les éléments de cache non référencés, prévisualisez séparément le plan de l'outil installé :

hf cache prune --dry-run

Une révision non référencée peut encore être requise par un script épinglé à son commit. Vérifiez ces projets avant d'accepter un élagage. N'utilisez pas un indicateur de confirmation global pour contourner cet examen.

Confrontez un plan d'élagage à de vrais projets

Une référence de branche ou d'étiquette dans le cache n'est pas un inventaire complet de ce dont vos projets ont besoin. Un script peut nommer un hachage de révision exact qui n'est plus la pointe de branche mise en cache. Avant d'accepter un élagage, recherchez l'ID de modèle et la révision épinglée dans la configuration des projets actifs, et conservez une copie de tout ce qui est nécessaire pour un travail hors ligne ou reproductible.

La documentation actuelle de la CLI inclut aussi les téléchargements .incomplete interrompus dans le comportement d'élagage. Terminez ou arrêtez le téléchargement concerné avant d'examiner le plan. Un fichier partiel laissé par un téléchargement interrompu est différent d'un fichier qu'un autre processus en cours d'exécution écrit encore.

Après une suppression examinée, relancez l'inventaire pour le même chemin de cache explicite et comparez l'espace disponible sur le même lecteur. Exécutez ensuite une petite charge de travail représentative. Si elle télécharge immédiatement à nouveau un grand modèle, cette charge de travail nécessite encore les données supprimées ; répéter le nettoyage ne fera qu'échanger de l'espace disque contre du temps de téléchargement.

Pour un déplacement, tenez l'état d'authentification hors de l'opération, sauf si le déplacer est intentionnel. Pointer uniquement HF_HUB_CACHE vers un autre lecteur est plus ciblé que déplacer tout HF_HOME. Notez l'ancienne valeur avant de la modifier, redémarrez l'application concernée et vérifiez où apparaît son prochain téléchargement réel. Si l'application continue d'utiliser l'ancien répertoire, examinez son chemin de cache explicite avant de supprimer l'une ou l'autre copie.

Déplacer les futurs téléchargements sans confondre les emplacements

Pour placer le cache Hub sur un autre lecteur, configurez HF_HUB_CACHE pour l'application qui le possède, puis redémarrez complètement cette application. Les modifications d'environnement doivent être présentes avant l'import de la bibliothèque. Un cache_dir propre à l'application peut encore pointer ailleurs, vérifiez donc la destination réelle du prochain téléchargement.

Modifier la variable ne déplace pas les anciens fichiers. Conservez l'ancien cache jusqu'à ce que le nouvel emplacement ait été testé et que tout élément local requis soit préservé. Si l'ancien répertoire est encore volumineux, examinez-le explicitement avec l'outil de cache et son chemin.

Après le nettoyage, testez une charge de travail importante et comparez l'espace libre sur le même volume. Pour le stockage de modèles distinct d'Ollama, utilisez le guide de migration Ollama. Une image de marque commune autour de l'IA ne signifie pas que les outils partagent un seul cache ou une seule commande de suppression sûre.