# Comprendre la mise en cache `huggingface_hub` utilise un cache local basé sur des fichiers pour stocker les fichiers individuels téléchargés depuis le Hub et éviter de retélécharger les fichiers inchangés lors d’une mise à jour d’un dépôt. De plus, `hf_xet` stocke un cache de shards et des données de staging pour optimiser les téléversements (voir [Cache Xet](#xet-caching)). > [!TIP] > Ce guide présente les outils de gestion du cache spécifiques à Python fournis par `huggingface_hub`. Pour une vue d’ensemble indépendante du langage sur le fonctionnement du système de cache du Hugging Face Hub, consultez la [documentation du Hub sur la mise en cache locale](https://huggingface.co/docs/hub/local-cache). ## Mise en cache basée sur les fichiers Le système de cache du Hugging Face Hub est conçu pour être le cache central partagé entre les bibliothèques qui dépendent du Hub. Il a été mis à jour dans la v0.8.0 pour éviter le téléchargement à nouveau des mêmes fichiers entre les révisions. Le système de cache est conçu comme suit : ``` ├─ ├─ ├─ ├─ ``` Le `` par défaut est `~/.cache/huggingface/hub`. Il est toutefois personnalisable via l'argument `cache_dir` sur toutes les méthodes, ou en spécifiant la variable d'environnement `HF_HOME` ou `HF_HUB_CACHE`. Les modèles, les jeux de données, les espaces et les noyaux partagent une racine commune. Chacun de ces dépôts contient le type de dépôt, l’espace de noms (organisation ou nom d’utilisateur) s’il existe et le nom du dépôt : ``` ├─ models--julien-c--EsperBERTo-small ├─ models--lysandrejik--arxiv-nlp ├─ models--bert-base-cased ├─ datasets--glue ├─ datasets--huggingface--DataMeasurementsFiles ├─ spaces--dalle-mini--dalle-mini ``` C'est dans ces dossiers que tous les fichiers seront désormais téléchargés depuis le Hub. La mise en cache garantit qu'un fichier n'est pas téléchargé deux fois s'il existe déjà et n'a pas été mis à jour ; mais s'il a été mis à jour et que vous demandez le fichier le plus récent, celui-ci sera téléchargé (le fichier précédent étant conservé intact au cas où vous en auriez à nouveau besoin). Pour y parvenir, tous les dossiers contiennent le même squelette : ``` ├─ datasets--glue │ ├─ refs │ ├─ blobs │ ├─ snapshots │ ├─ trees ... ``` Chaque dossier est conçu pour contenir les éléments suivants : ### Références Le dossier `refs` contient des fichiers qui indiquent la dernière révision de la référence donnée. Par exemple, si nous avons précédemment récupéré un fichier de la branche `main` d'un dépôt, le dossier `refs` contiendra un fichier nommé `main`, qui contiendra lui-même l'identifiant de commit de la tête actuelle. Si le dernier commit de `main` a `aaaaaa` comme identifiant, alors il contiendra `aaaaaa`. Si cette même branche est mise à jour avec un nouveau commit, dont l’identifiant est `bbbbbb`, alors le téléchargement à nouveau d’un fichier depuis cette référence mettra à jour le fichier `refs/main` pour qu’il contienne `bbbbbb`. ### Blobs Le dossier `blobs` contient les fichiers réellement téléchargés. Le nom de chaque fichier est son hachage. ### Instantanés Le dossier `snapshots` contient des liens symboliques vers les blobs mentionnés ci-dessus. Il est lui-même composé de plusieurs dossiers : un par révision connue ! Dans l’explication ci-dessus, nous avions d’abord récupéré un fichier de la révision `aaaaaa`, avant de récupérer un fichier de la révision `bbbbbb`. Dans cette situation, nous aurions maintenant deux dossiers dans le dossier `snapshots` : `aaaaaa` et `bbbbbb`. Chacun de ces dossiers contient des liens symboliques vivants portant les noms des fichiers que nous avons téléchargés. Par exemple, si nous avions téléchargé le fichier `README.md` à la révision `aaaaaa`, nous aurions le chemin suivant : ``` //snapshots/aaaaaa/README.md ``` Le fichier `README.md` est en réalité un lien symbolique pointant vers le blob qui contient l'empreinte du fichier. En créant le squelette de cette manière, nous ouvrons la voie au partage de fichiers : si le même fichier avait été récupéré dans la révision `bbbbbb`, il aurait le même hachage et le fichier n’aurait pas besoin d’être à nouveau téléchargé. ### Arbres Le dossier `trees` met en cache la liste des fichiers contenus dans un dépôt à un commit donné. Un commit étant immuable, sa liste de fichiers ne change jamais. Cela signifie que la liste peut être mise en cache indéfiniment sans jamais avoir besoin d’être vérifiée à nouveau sur le Hub. Chaque liste mise en cache est nommée d’après un hachage de commit et stockée sous forme de fichier JSON, par exemple `trees/aaaaaa.json`. Pour chaque fichier du dépôt à ce commit, elle enregistre les informations nécessaires pour télécharger le fichier : son chemin, sa taille et son hachage. Il s’agit des mêmes informations que le Hub renverrait autrement, mais il faut normalement un appel réseau par fichier pour les récupérer. Ce cache est écrit par [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.snapshot_download). La première fois que vous téléchargez un commit, la liste des fichiers est récupérée une fois et enregistrée ici. La fois suivante, lorsque vous téléchargez le même commit, la liste est lue depuis le disque au lieu d’être récupérée à nouveau. En conséquence, relancer un téléchargement lorsque tout est déjà en cache ne coûte qu’un seul appel réseau : celui nécessaire pour résoudre le nom de la branche ou de la balise en un hachage de commit. Les fonctions [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.snapshot_download) et [hf_hub_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.hf_hub_download) lisent ce cache pour éviter les appels réseau. Lorsque vous téléchargez un fichier en utilisant un hachage de commit comme révision (c'est exactement ce que fait [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.snapshot_download) en interne pour chaque fichier), les métadonnées de téléchargement sont lues depuis la liste de fichiers mise en cache et l'appel réseau par fichier est ignoré. Cela signifie qu'un appel à [hf_hub_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.hf_hub_download) pour un seul fichier bénéficie également d'une liste de fichiers enregistrée par un appel antérieur à [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.snapshot_download) pour le même commit. La liste de fichiers en cache décrit exactement ce qu'un commit doit contenir, [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.snapshot_download) peut donc également déterminer si un instantané local est complet. Si le Hub est inaccessible (vous êtes hors ligne, la connexion échoue, ou vous avez passé `local_files_only=True`) et que certains fichiers attendus manquent dans l'instantané local, [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.snapshot_download) lève [IncompleteSnapshotError](/docs/huggingface_hub/v2.4.0/fr/package_reference/utilities#huggingface_hub.errors.IncompleteSnapshotError) au lieu de retourner un dossier partiel. Avant cela, un instantané incomplet était retourné silencieusement, ce qui pouvait vous amener à travailler avec des fichiers manquants sans le savoir. Les fichiers exclus par `allow_patterns` ou `ignore_patterns` ne sont pas comptés comme manquants. L'exception expose le chemin de l'instantané incomplet via son attribut `snapshot_path`, ce qui vous permet toujours de localiser les fichiers partiellement en cache si nécessaire. ### .no_exist (avancé) En plus des dossiers `blobs`, `refs` et `snapshots`, vous pouvez également trouver un dossier `.no_exist` dans votre cache. Ce dossier suit les fichiers que vous avez tenté de télécharger une fois mais qui n'existent pas sur le Hub. Sa structure est identique à celle du dossier `snapshots`, avec un sous-dossier par révision connue : ``` //.no_exist/aaaaaa/config_that_does_not_exist.json ``` Contrairement au dossier `snapshots`, les fichiers sont de simples fichiers vides (pas de liens symboliques). Dans cet exemple, le fichier `"config_that_does_not_exist.json"` n'existe pas sur le Hub pour la révision `"aaaaaa"`. Comme il ne stocke que des fichiers vides, ce dossier est négligeable en termes d'espace disque. Vous vous demandez peut-être pourquoi cette information est pertinente. Dans certains cas, un framework tente de charger des fichiers optionnels pour un modèle. Enregistrer l’absence de fichiers optionnels accélère le chargement du modèle, car cela évite un appel HTTP par fichier optionnel possible. C’est le cas, par exemple, dans `transformers`, où chaque tokenizer peut prendre en charge des fichiers supplémentaires. La première fois que vous chargez le tokenizer sur votre machine, il met en cache les fichiers optionnels existants (et ceux qui n’existent pas) afin de réduire le temps de chargement lors des initialisations suivantes. Pour tester si un fichier est mis en cache localement (sans effectuer de requête HTTP), vous pouvez utiliser l'assistant [try_to_load_from_cache()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.try_to_load_from_cache). Il renverra le chemin du fichier (s'il existe et est en cache), l'objet `_CACHED_NO_EXIST` (si son absence est en cache) ou `None` (si nous ne le savons pas). ```python 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 pratique En pratique, votre cache doit ressembler à l'arborescence suivante : ```text [ 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.json ``` ### CACHEDIR.TAG `huggingface_hub` crée automatiquement un fichier [`CACHEDIR.TAG`](https://bford.info/cachedir/) à l’intérieur du répertoire de cache. Ce fichier suit la *Cache Directory Tagging Standard* et indique aux outils de sauvegarde (par exemple Borg, restic, rsync) que le répertoire contient des données de cache téléchargeables à nouveau et peut donc être exclu en toute sécurité des sauvegardes. ### Limites Afin de disposer d'un système de cache efficace, `huggingface-hub` utilise des liens symboliques. Cependant, les liens symboliques ne sont pas pris en charge sur toutes les machines. Il s'agit d'une limitation connue, notamment sur Windows. Dans ce cas, `huggingface_hub` n'utilise pas le répertoire `blobs/` mais stocke directement les fichiers dans le répertoire `snapshots/`. Ce contournement permet aux utilisateurs de télécharger et de mettre en cache les fichiers du Hub de la même manière. Les outils d'inspection et de suppression du cache (voir ci-dessous) sont également pris en charge. Toutefois, le système de cache est moins efficace, car un fichier unique peut être téléchargé plusieurs fois si plusieurs révisions du même dépôt sont téléchargées. Si vous souhaitez profiter du système de cache basé sur les liens symboliques sur une machine Windows, vous devez soit [activer le mode développeur](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development), soit exécuter Python en tant qu'administrateur. Si vous souhaitez utiliser de manière proactive le mode de cache sans lien symbolique (par exemple sur un système de fichiers partagé qui ne gère pas bien les liens symboliques), vous pouvez définir la variable d’environnement [`HF_HUB_DISABLE_SYMLINKS`](../package_reference/environment_variables#hfhubdisablesymlinks) sur `1`. Les fichiers seront copiés directement dans `snapshots/` au lieu d’être liés symboliquement à `blobs/`. Lorsque les liens symboliques ne sont pas pris en charge, un message d'avertissement est affiché pour informer l'utilisateur qu'il utilise une version dégradée du système de cache. Cet avertissement peut être désactivé en définissant la variable d'environnement `HF_HUB_DISABLE_SYMLINKS_WARNING` sur true. ### Blobs partagés entre les dépôts Par défaut, les fichiers Xet sont également dédupliqués entre les dépôts. Un fichier Xet téléchargé via `hf_xet` est stocké une seule fois dans `/blobs//`, et l'entrée `blobs/` du dépôt est un lien symbolique relatif pointant vers ce fichier. Lorsqu'un autre dépôt a besoin du même fichier, il reçoit un lien symbolique au lieu d'un téléchargement : aucun octet n'est transféré et aucun espace supplémentaire n'est utilisé. La structure des instantanés ne change pas. Un fichier marqueur identifie le magasin, de sorte qu'un répertoire `blobs` qui n'a pas été créé par `huggingface_hub` n'est jamais modifié. Chaque fichier partagé possède un manifeste `.refs` qui répertorie les blobs du dépôt qui l’utilisent. `hf cache rm` le lit pour ne vérifier que les fichiers partagés affectés par une suppression, et `hf cache prune` supprime les fichiers partagés qui ne sont plus utilisés par aucun dépôt en cache. Le manifeste n’est qu’un indice : chaque entrée est vérifiée par rapport au système de fichiers, et un fichier dont les métadonnées sont manquantes ou illisibles est conservé. Le nettoyage privilégie la conservation de données récupérables plutôt que la rupture d’une entrée de cache valide. Les tailles par dépôt restent logiques, de sorte qu'un fichier partagé est compté pour chaque dépôt qui l'utilise. La taille `size_on_disk` de l'ensemble du cache est physique : chaque fichier partagé est compté une seule fois, y compris les fichiers qu'aucun dépôt n'utilise plus. Les anciens clients (`huggingface_hub`, `huggingface.js`, `hf-hub`, `llama.cpp`, et tout ce qui suit les liens symboliques) continuent de lire et de télécharger normalement, dans les mêmes dossiers de dépôt. Deux limitations : - `huggingface_hub<=1.31` laisse les fichiers partagés d’un dépôt supprimé dans le store, où `hf cache ls` les signale et `hf cache prune` les supprime. Les outils de suppression de cache d’autres clients peuvent au contraire supprimer un fichier partagé encore utilisé par d’autres dépôts ; les fichiers concernés sont alors ré-telechargés lors de leur prochaine utilisation. Utilisez une version à jour de `huggingface_hub` pour `hf cache rm`, `hf cache prune` et la suppression programmatique. - Leurs analyseurs de cache peuvent signaler le répertoire `blobs` de premier niveau comme une entrée inconnue. Le magasin requiert la structure de cache basée sur les liens symboliques et est désactivé par `HF_HUB_DISABLE_XET=1`. Tout échec lors du partage d’un fichier, tel qu’un système de fichiers non pris en charge, une erreur d’autorisation ou un répertoire `blobs` existant non marqué, bascule silencieusement sur le stockage local du dépôt. Définissez [`HF_HUB_DISABLE_SHARED_BLOBS=1`](../package_reference/environment_variables#hfhubdisablesharedblobs) pour y renoncer entièrement. ## Épingler une révision (avancé) > [!TIP] > Si vous intégrez le Hub dans une bibliothèque ML, un seul appel à [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.snapshot_download) reste l’approche recommandée : il résout la révision une seule fois, télécharge tout en parallèle et met en cache la liste des fichiers. Ce qui suit n’est utile que pour les bibliothèques complexes qui téléchargent et chargent de nombreux composants séparément (config, poids, tokenizer, processeur, adaptateurs, ...) et ne peuvent pas utiliser un seul appel. Lorsqu’une bibliothèque télécharge plusieurs fichiers un par un, chaque appel doit à nouveau résoudre `revision="main"` en un hachage de commit. Cela coûte un appel HTTP par fichier et, pire encore, deux appels effectués à quelques secondes d’intervalle peuvent aboutir à deux commits différents si le dépôt est mis à jour entre-temps. [HfApi.resolve_revision()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) résout la révision une seule fois et renvoie un [ResolvedRevision](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.ResolvedRevision) : ```py >>> from huggingface_hub import resolve_revision >>> revision = resolve_revision("openai-community/gpt2") >>> revision ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e') ``` [ResolvedRevision](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.ResolvedRevision) est une sous-classe de `str`, il peut donc être transmis à toute méthode de `huggingface_hub` acceptant un argument `revision`. Sa valeur en chaîne de caractères correspond à ce que l’utilisateur a initialement demandé (`"main"` ici, d’où des messages d’erreur lisibles), tandis que `.resolved` contient l’identifiant de commit : ```py >>> revision == "main" True >>> revision.resolved '607a30d783dfa663caf39e06633721c8d4cfcd7e' ``` Les utilitaires de téléchargement ([hf_hub_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.hf_hub_download), [snapshot_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.snapshot_download), [get_cached_repo_tree()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.get_cached_repo_tree)) détectent un [ResolvedRevision](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.ResolvedRevision) et utilisent directement l’empreinte de commit. Chaque fichier est garanti de provenir du même commit, et une fois les fichiers mis en cache, aucun appel HTTP n’est nécessaire : ```py >>> 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) ``` La correspondance `revision` -> `commit hash` est également écrite dans le dossier `refs/` du cache (voir [Refs](#refs)). Cela signifie que si le Hub ne peut pas être atteint ultérieurement (mode hors ligne, erreur de connexion, délai d’attente, indisponibilité du Hub), [HfApi.resolve_revision()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) bascule de manière transparente sur la valeur mise en cache. Si rien n’est mis en cache non plus, une [RevisionResolutionError](/docs/huggingface_hub/v2.4.0/fr/package_reference/utilities#huggingface_hub.errors.RevisionResolutionError) est levée. Un hash de commit n’a de sens que pour le dépôt auquel il a été résolu, et les utilitaires de téléchargement l’utilisent tel quel. Ainsi, un [ResolvedRevision](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.ResolvedRevision) ne doit être transmis qu’au dépôt pour lequel il a été résolu. Si une bibliothèque télécharge également depuis un autre dépôt (un modèle de base, un adaptateur, un composant hébergé dans son propre dépôt, ...), elle a besoin d’une révision résolue pour ce dépôt. Il suffit de renvoyer le [ResolvedRevision](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.ResolvedRevision) à [HfApi.resolve_revision()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) : ce dernier se souvient du dépôt auquel il appartient et résout à nouveau la révision initialement demandée (`"main"` ici) pour le nouveau dépôt. ```py >>> 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) ``` ## Mise en cache Xet Pour fournir des téléversements plus efficaces, `hf_xet` ajoute un répertoire `xet` au cache existant de `huggingface_hub`. Il y stocke les shards (une structure de données qui associe les fichiers à des chunks) ainsi que les données de staging utilisées pour la déduplication et la reprise des téléversements. Pour plus d'informations sur le système de stockage Xet, consultez cette [section](https://huggingface.co/docs/hub/xet/index). `hf_xet` n’utilise plus de cache local de chunks pour les téléchargements. La définition de `HF_XET_CHUNK_CACHE_SIZE_BYTES` n’en active pas un. Les fichiers téléchargés sont toujours mis en cache dans le [cache basé sur les fichiers](#file-based-caching). Le répertoire `xet`, situé par défaut à `~/.cache/huggingface/xet`, peut être configuré avec [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache). Il présente la structure suivante : ```bash ├─ xet │ ├─ environment_identifier │ │ ├─ shard-cache │ │ ├─ staging ``` Le répertoire `environment_identifier` est une chaîne encodée (il peut apparaître sur votre machine sous la forme `https___cas_serv-tGqkUaZf_CBPHQ6h`). Il est utilisé pendant le développement, permettant ainsi à des versions locales et de production du cache de coexister simultanément. Il est également utilisé lors du téléchargement depuis des dépôts situés dans des [régions de stockage](https://huggingface.co/docs/hub/storage-regions) différentes. Vous pouvez voir plusieurs entrées de ce type dans le répertoire `xet`, chacune correspondant à un environnement différent, mais leur structure interne est identique. Les répertoires internes servent aux fins suivantes : * `shard-cache` contient des shards en cache utilisés sur le chemin de téléversement. * `staging` est un espace de travail conçu pour prendre en charge les téléversements reprenables. Ils sont documentés ci-dessous. Le cache de shards et les données de staging sont gérés par `hf_xet` en tant que couche d’optimisation pour les téléversements. Pour gérer les fichiers téléchargés, utilisez les API de cache basées sur les fichiers de `huggingface_hub`. ### `shard-cache` Ce cache est utilisé lors de la mise en ligne de contenu sur le Hub. Le répertoire est à plat, ne contenant que des fichiers de shards, chacun utilisant un ID comme nom de shard. ```sh ├─ xet │ ├─ environment_identifier │ │ ├─ shard-cache │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb │ │ │ ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb ``` Le `shard-cache` contient des shards qui sont : - Généré localement et téléversé avec succès dans le CAS - Téléchargé depuis CAS dans le cadre de l'algorithme de déduplication global Les shards fournissent une correspondance entre les fichiers et les chunks. Lors des téléversements, chaque fichier est découpé en chunks et l’empreinte (hash) de chaque chunk est enregistrée. Chaque shard du cache est ensuite consulté. Si un shard contient un hash de chunk présent dans le fichier local en cours de téléversement, ce chunk peut être écarté, car il est déjà stocké dans le CAS. Tous les shards ont une date d'expiration de 3 à 4 semaines à compter de leur téléchargement. Les shards expirés ne sont pas chargés lors de la mise en ligne et sont supprimés une semaine après leur expiration. ### `staging` Lorsqu'un téléversement s'interrompt avant que le nouveau contenu n'ait été validé dans le dépôt, vous devez reprendre le transfert du fichier. Toutefois, il est possible que certains blocs aient été téléversés avec succès avant l'interruption. Afin de ne pas avoir à recommencer depuis le début, le répertoire `staging` sert d'espace de travail pendant les téléversements, en stockant les métadonnées des segments téléversés avec succès. Le répertoire `staging` a la structure suivante : ``` ├─ xet │ ├─ environment_identifier │ │ ├─ staging │ │ │ ├─ shard-session │ │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ │ ├─ xorb-metadata │ │ │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb ``` Lorsque les fichiers sont traités et que les fragments sont téléversés avec succès, leurs métadonnées sont stockées dans `xorb-metadata` sous forme de shard. Lors de la reprise d’une session de téléversement, chaque fichier est à nouveau traité et les shards de ce répertoire sont consultés. Tout contenu déjà téléversé avec succès est ignoré, et tout nouveau contenu est téléversé (et ses métadonnées sont enregistrées). Pendant ce temps, `shard-session` stocke les informations de fichiers et de fragments pour les fichiers traités. Une fois le téléchargement terminé avec succès, le contenu de ces fragments est déplacé vers le `shard-cache` plus persistant. ### Limites et restrictions Le `shard-cache` a une limite souple de 16 Go, configurable via la variable d’environnement [`HF_XET_SHARD_CACHE_SIZE_LIMIT`](../package_reference/environment_variables#hfxetshardcachesizelimit). Il n’existe pas d’API de haut niveau pour gérer ce cache. Le cache de shards et les données de staging sont utilisés pour optimiser les téléversements. Pour interagir avec les actifs eux-mêmes, il est recommandé d’utiliser les [API du système de cache de `huggingface_hub`](https://huggingface.co/docs/huggingface_hub/guides/manage-cache). Si vous devez libérer l’espace utilisé par Xet ou déboguer d’éventuels problèmes liés au cache, supprimez simplement le cache `xet` en exécutant `rm -rf ~//xet`, où `` est l’emplacement de votre cache Hugging Face, généralement `~/.cache/huggingface`. Exemple d'arborescence du répertoire de cache `xet` : ```sh ├─ xet │ ├─ environment_identifier │ │ ├─ shard-cache │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb │ │ │ ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb │ │ ├─ staging │ │ │ ├─ shard-session │ │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ │ ├─ xorb-metadata │ │ │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb ``` Pour en savoir plus sur Xet Storage, consultez cette [section](https://huggingface.co/docs/hub/xet/index). ## Mise en cache des ressources En plus de mettre en cache les fichiers du Hub, les bibliothèques en aval exigent souvent de mettre en cache d'autres fichiers liés à HF mais non gérés directement par `huggingface_hub` (par exemple : fichiers téléchargés depuis GitHub, données prétraitées, journaux, etc.). Pour mettre en cache ces fichiers, appelés `assets`, on peut utiliser [cached_assets_path()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.cached_assets_path). Ce petit utilitaire génère des chemins dans le cache HF de manière unifiée, en se basant sur le nom de la bibliothèque qui en fait la demande et, le cas échéant, sur un espace de noms et un nom de sous-dossier. L'objectif est de laisser chaque bibliothèque en aval gérer ses assets à sa manière (par exemple : aucune règle sur la structure), à condition qu'elle reste dans le bon dossier d'assets. Ces bibliothèques peuvent ensuite s'appuyer sur les outils de `huggingface_hub` pour gérer le cache, en particulier pour parcourir et supprimer des parties des assets via une commande CLI. ```py 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 ! ``` > [!TIP] > [cached_assets_path()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.cached_assets_path) est la méthode recommandée pour stocker les ressources, mais elle n’est pas obligatoire. Si votre bibliothèque utilise déjà son propre cache, n’hésitez pas à l’utiliser ! ### Les assets en pratique En pratique, votre cache d'actifs doit ressembler à l'arborescence suivante : ```text 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/ └── (...) ``` ## Gérer votre cache basé sur des fichiers ### Inspecter votre cache Pour l’instant, les fichiers en cache ne sont jamais supprimés de votre répertoire local : lorsque vous téléchargez une nouvelle révision d’une branche, les fichiers précédents sont conservés au cas où vous en auriez à nouveau besoin. Il peut donc être utile d’inspecter votre répertoire de cache afin de savoir quels dépôts et quelles révisions occupent le plus d’espace disque. `huggingface_hub` fournit des utilitaires que vous pouvez utiliser depuis l’interface en ligne de commande `hf` ou depuis Python. **Inspecter le cache depuis le terminal** Exécutez `hf cache ls` pour explorer ce qui est stocké localement. Par défaut, la commande agrège les informations par dépôt : ```text ➜ 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. ``` Ajoutez `--revisions` pour lister chaque instantané mis en cache et enchaînez les filtres pour vous concentrer sur l’essentiel. Les filtres comprennent les tailles et durées lisibles par l’humain, de sorte que des expressions telles que `size>1GB` ou `accessed>30d` fonctionnent immédiatement : ```text ➜ 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. ``` Besoin d’une sortie exploitable par une machine ? Utilisez `--format json` pour obtenir des objets structurés ou `--format csv` pour des tableurs. Sinon, `--quiet` n’affiche que les identifiants (un par ligne) afin de pouvoir les transmettre à d’autres outils. Utilisez `--sort` pour trier les entrées par `accessed`, `modified`, `name` ou `size` (ajoutez `:asc` ou `:desc` pour contrôler l’ordre) et `--limit` pour limiter les résultats aux N premières entrées. Combinez ces options avec `--cache-dir` lorsque vous devez inspecter un cache stocké en dehors de `HF_HOME`. **Filtrer avec des outils shell courants** Une sortie tabulaire signifie que vous pouvez continuer à utiliser les outils que vous connaissez déjà. Par exemple, l'extrait de code ci-dessous trouve toutes les révisions en cache associées à `t5-small` : ```text ➜ 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 ``` **Inspecter le cache depuis Python** Pour un usage plus avancé, utilisez [scan_cache_dir()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.scan_cache_dir), l'utilitaire Python appelé par l'outil CLI. Vous pouvez l'utiliser pour obtenir un rapport détaillé structuré autour de 4 dataclasses : - [HFCacheInfo](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.HFCacheInfo) : rapport complet renvoyé par [scan_cache_dir()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.scan_cache_dir) - [CachedRepoInfo](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.CachedRepoInfo) : informations sur un dépôt mis en cache - [CachedRevisionInfo](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.CachedRevisionInfo) : informations sur une révision mise en cache (par exemple « snapshot ») au sein d’un dépôt - [CachedFileInfo](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.CachedFileInfo) : informations sur un fichier mis en cache dans un instantané Voici un exemple d'utilisation simple. Consultez la référence pour plus de détails. ```py >>> 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(...), ... ], ) ``` ### Vérifier votre cache `huggingface_hub` peut vérifier que vos fichiers en cache correspondent aux sommes de contrôle du Hub. Utilisez la commande CLI `hf cache verify` pour valider la cohérence des fichiers d’une révision spécifique d’un dépôt spécifique : ```bash >>> 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. ``` Vérifier une révision mise en cache spécifique : ```bash >>> hf cache verify meta-llama/Llama-3.1-8B-Instruct --revision 0e9e39f249a16976918f6564b8830bc894c89659 ``` > [!TIP] > Consultez la [référence de la CLI `hf cache verify`](../package_reference/cli#hf-cache-verify) pour plus de détails sur l'utilisation et la liste complète des options. ### Nettoyer votre cache Analyser votre cache est intéressant, mais ce que vous voulez généralement faire ensuite, c'est supprimer certaines parties pour libérer de l'espace sur votre disque. C'est possible à l'aide des commandes CLI `hf cache rm` et `hf cache prune`. On peut également utiliser de manière programmatique les fonctions d'aide [delete_revisions()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.HFCacheInfo.delete_revisions) et [delete_files()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.HFCacheInfo.delete_files) de l'objet [HFCacheInfo](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.HFCacheInfo) renvoyé lors de l'analyse du cache. **Stratégie de suppression** Pour supprimer une partie du cache, vous devez passer une liste de révisions à supprimer. L’outil définit une stratégie de libération de l’espace sur la base de cette liste. Il renvoie un objet [DeleteCacheStrategy](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.DeleteCacheStrategy) qui décrit les fichiers et dossiers qui seront supprimés. L’objet [DeleteCacheStrategy](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.DeleteCacheStrategy) vous indique la quantité d’espace attendue à libérer. Une fois que vous êtes d’accord avec la suppression, vous devez l’exécuter pour qu’elle prenne effet. Afin d’éviter toute incohérence, vous ne pouvez pas modifier manuellement un objet de stratégie. La stratégie pour supprimer les révisions est la suivante : - le dossier `snapshot` contenant les liens symboliques de révision est supprimé. - Les fichiers blobs qui ne sont ciblés que par des révisions à supprimer sont également supprimés. - si une révision est liée à un ou plusieurs `refs`, les références sont supprimées. - si toutes les révisions d'un dépôt sont supprimées, le dépôt en cache est supprimé dans son intégralité. La suppression de fichiers individuels avec [delete_files()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.HFCacheInfo.delete_files) suit la même logique : les entrées de snapshot sont supprimées, et leurs blobs ne sont supprimés que si aucun autre fichier en cache ne les référence. Les refs et les dossiers de snapshot sont conservés. > [!TIP] > Les hachures de révision sont uniques pour tous les dépôts. `hf cache rm` accepte donc soit un identifiant de dépôt (par exemple `model/bert-base-uncased`), soit un hachure de révision seul ; lorsqu'un hachure est fourni, il n'est pas nécessaire de spécifier le dépôt séparément. > [!WARNING] > Si une révision n'est pas trouvée dans le cache, elle est ignorée silencieusement. De plus, si un fichier ou un dossier ne peut pas être trouvé lors de la tentative de suppression, un avertissement est consigné dans le journal, mais aucune erreur n'est levée. La suppression se poursuit pour les autres chemins contenus dans l'objet [DeleteCacheStrategy](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.DeleteCacheStrategy). **Nettoyer le cache depuis le terminal** Utilisez `hf cache rm` pour supprimer définitivement des dépôts ou des révisions de votre cache. Transmettez un ou plusieurs identifiants de dépôt (par exemple `model/bert-base-uncased`) ou des hachages de révision : ```text ➜ 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. ``` Vous pouvez également utiliser `hf cache rm` en combinaison avec `hf cache ls --quiet` pour supprimer en masse les entrées identifiées par un filtre : ```bash >>> 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. ``` Mélangez des dépôts et des révisions dans le même appel. Ajoutez `--dry-run` pour prévisualiser l’impact, ou `--yes` pour ignorer la demande de confirmation lors de l’automatisation : ```text ➜ 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. ``` Pour supprimer un fichier unique plutôt qu’un dépôt entier, par exemple une quantification GGUF, passez un URI de fichier `hf://`. Le fichier est supprimé de toutes les révisions mises en cache du dépôt, et son blob est supprimé uniquement si aucun autre fichier mis en cache ne le référence encore. La révision reste utilisable, et un fichier supprimé est à nouveau téléchargé la prochaine fois qu’il est nécessaire. Les chemins doivent correspondre exactement : les dossiers et les motifs glob ne sont pas pris en charge. ```text ➜ 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. ``` Lorsque vous travaillez hors de l'emplacement de cache par défaut, associez la commande à `--cache-dir PATH`. Pour nettoyer les résidus du cache en masse, exécutez `hf cache prune`. Cette commande supprime automatiquement les révisions qui ne sont plus référencées par une branche ou un tag, les fichiers `.incomplete` résiduels issus de téléchargements interrompus, ainsi que les blobs partagés qui ne sont plus référencés par aucun dépôt en cache : ```text ➜ 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. ``` Les fichiers `.incomplete` sont des blobs partiels laissés derrière lors d’une interruption de téléchargement. Ils ne sont pas suivis par le scan basé sur les révisions, de sorte que `hf cache ls` ne les signale que par un indice (`Found X incomplete download(s) ...`), tandis que `hf cache prune` est la commande qui les supprime réellement. `hf cache rm` ne les touche jamais, sauf lorsqu’elle supprime un dépôt entier. Les deux commandes prennent en charge `--dry-run`, `--yes` et `--cache-dir`, ce qui vous permet d'effectuer un aperçu, d'automatiser et de cibler des répertoires de cache alternatifs au besoin. **Nettoyer le cache depuis Python** Pour plus de flexibilité, vous pouvez également utiliser la méthode [delete_revisions()](/docs/huggingface_hub/v2.4.0/fr/package_reference/cache#huggingface_hub.HFCacheInfo.delete_revisions) de manière programmatique. Voici un exemple simple. Consultez la référence pour plus de détails. ```py >>> 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() ```