Hub Python Library documentation

Référence du système de cache

Hub Python Library

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v2.4.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Référence du système de cache

Le système de cache a été mis à jour dans la v0.8.0 pour devenir le système de cache central partagé entre les bibliothèques qui dépendent du Hub. Consultez le guide du système de cache pour une présentation détaillée du cache sur HF.

Aides

try_to_load_from_cache

huggingface_hub.try_to_load_from_cache

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

Paramètres

cache_dir (str ou os.PathLike) — Le dossier où se trouvent les fichiers mis en cache.
repo_id (str) — L'identifiant du dépôt sur huggingface.co.
filename (str) — Le nom du fichier à rechercher dans repo_id.
revision (str, facultatif) — La version spécifique du modèle à utiliser. Par défaut, "main" est utilisé si aucune valeur n’est fournie et qu’aucun commit_hash n’est non plus fourni.
repo_type (str, facultatif) — Le type du dépôt. La valeur par défaut est "model".

Retourne

Optional[str] ou _CACHED_NO_EXIST

Retournera None si le fichier n'a pas été mis en cache. Sinon :

Le chemin exact du fichier en cache s'il est trouvé dans le cache
Une valeur spéciale _CACHED_NO_EXIST si le fichier n'existe pas à l'empreinte de commit donnée et que ce fait a été mis en cache.

Explore le cache pour retourner le dernier fichier mis en cache pour une révision donnée, s'il est trouvé.

Cette fonction ne lève aucune exception si le fichier n'est pas mis en cache.

Exemple :

from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST

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

cached_assets_path

huggingface_hub.cached_assets_path

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

Paramètres

library_name (str) — Nom de la bibliothèque qui gérera le dossier de cache. Exemple : "dataset".
namespace (str, facultatif, valeur par défaut “default”) — Espace de noms auquel les données appartiennent. Exemple : "SQuAD".
subfolder (str, facultatif, par défaut “default”) — Sous-dossier dans lequel les données seront stockées. Exemple : extracted.
assets_dir (str, Path, facultatif) — Chemin vers le dossier où les ressources sont mises en cache. Ce dossier ne doit pas être le même que celui où les fichiers du Hub sont mis en cache. Par défaut, HF_HOME / "assets" si non fourni. Peut également être défini avec la variable d’environnement HF_ASSETS_CACHE.

Retourner un chemin de dossier pour mettre en cache des fichiers arbitraires.

huggingface_hub fournit un chemin de dossier canonique pour stocker les ressources. C'est la méthode recommandée pour intégrer le cache dans une bibliothèque en aval, car elle bénéficie des outils intégrés pour scanner et supprimer le cache correctement.

La distinction est faite entre les fichiers mis en cache depuis le Hub et les ressources. Les fichiers du Hub sont mis en cache de manière consciente de git et entièrement gérés par huggingface_hub. Consultez la documentation associée. Tous les autres fichiers mis en cache par une bibliothèque en aval sont considérés comme des « ressources » (fichiers téléchargés depuis des sources externes, extraits d'une archive .tar, prétraités pour l'entraînement, …).

Une fois le chemin du dossier généré, il est garanti qu’il existe et qu’il s’agit d’un répertoire. Le chemin repose sur trois niveaux de profondeur : le nom de la bibliothèque, un espace de noms et un sous-dossier. Ces trois niveaux offrent de la flexibilité tout en permettant à huggingface_hub de s’attendre à des dossiers lors du balayage ou de la suppression de parties du cache des ressources. Au sein d’une bibliothèque, il est attendu que tous les espaces de noms partagent le même sous-ensemble de noms de sous-dossiers, mais ce n’est pas une règle obligatoire. La bibliothèque aval a alors un contrôle total sur la structure de fichiers à adopter dans son cache. L’espace de noms et le sous-dossier sont optionnels (ils défaut à un sous-dossier "default/") mais le nom de la bibliothèque est obligatoire, car nous voulons que chaque bibliothèque aval gère son propre cache.

Arbre attendu :

    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/
                └── (...)

Exemple :

>>> from huggingface_hub import cached_assets_path

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

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

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

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

scan_cache_dir

huggingface_hub.scan_cache_dir

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

Paramètres

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

Analyser l’ensemble du système de cache HF et renvoyer une structure ~HFCacheInfo.

Utilisez scan_cache_dir pour scanner votre système de cache de manière programmatique. Le cache sera analysé dépôt par dépôt. Si un dépôt est corrompu, une ~CorruptedCacheException sera levée en interne mais capturée et retournée dans la structure ~HFCacheInfo. Seuls les dépôts valides font l’objet d’un rapport approprié.

>>> from huggingface_hub import scan_cache_dir

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

Vous pouvez également afficher un rapport détaillé directement depuis la ligne de commande hf en utilisant :

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

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

Lève :

CacheNotFound Si le répertoire de cache n'existe pas.

ValueError Si le répertoire de cache est un fichier au lieu d'un répertoire.

Retourne : un objet ~HFCacheInfo.

Structures de données

Toutes les structures sont construites et renvoyées par scan_cache_dir() et sont immuables.

HFCacheInfo

classe huggingface_hub.HFCacheInfo

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

Paramètres

size_on_disk (int) — Taille physique du système de cache en octets. Un blob partagé entre plusieurs dépôts est compté une seule fois, et les blobs partagés uniquement dans le stockage qui ne sont plus référencés par aucun dépôt sont inclus. Peut être inférieur à la somme des tailles par dépôt.
repos (frozenset[CachedRepoInfo]) — Ensemble de ~CachedRepoInfo décrivant tous les dépôts en cache valides trouvés sur le système de cache lors de l’analyse.
incomplete_files (frozenset[CachedIncompleteFileInfo]) — Ensemble de ~CachedIncompleteFileInfo décrivant les fichiers orphelins *.incomplete laissés par des téléchargements interrompus.
warnings (list[CorruptedCacheException]) — Liste des ~CorruptedCacheException survenues lors de l’analyse du cache. Ces exceptions sont capturées afin que l’analyse puisse se poursuivre. Les dépôts corrompus sont ignorés lors de l’analyse.
cache_dir (Path ou None) — Répertoire de cache qui a été analysé.

Structure de données figée contenant des informations sur l'ensemble du système de cache.

Cette structure de données est retournée par scan_cache_dir() et est immuable.

size_on_disk ne prend en compte que les blobs, et les dépôts corrompus sont ignorés. Il s’agit d’une taille physique : contrairement à CachedRepoInfo.size_on_disk, qui attribue un blob partagé à chaque dépôt qui y fait référence, un blob partagé n’est compté qu’une seule fois ici.

delete_files

( *files: CachedFileInfo )

Préparez la stratégie pour supprimer des fichiers mis en cache individuellement.

Seules les entrées de snapshot sont supprimées. Un blob n’est supprimé que si aucun autre fichier en cache ne le référence, de sorte que les blobs partagés avec d’autres révisions sont conservés. Les refs et les répertoires de snapshot sont également conservés, même si un snapshot finit par être vide. Pour supprimer des révisions ou des dépôts entiers, utilisez delete_revisions().

Exemple :

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

delete_revisions

( *revisions: str )

Préparez la stratégie pour supprimer une ou plusieurs révisions mises en cache localement.

Les révisions d’entrée peuvent être n’importe quel hachage de révision. Si un hachage de révision n’est pas trouvé dans le cache local, un avertissement est émis, mais aucune erreur n’est levée. Les révisions peuvent provenir de dépôts différents mis en cache, car les hachages sont uniques entre les dépôts,

Exemples :

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

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

delete_revisions renvoie un objet DeleteCacheStrategy qui doit être exécuté. Le DeleteCacheStrategy n’est pas destiné à être modifié, mais permet d’effectuer un essai à blanc avant d’exécuter réellement la suppression.

export_as_table

( verbosity: int = 0 ) → str

Paramètres

verbosity (int, facultatif) — Niveau de verbosité. Valeur par défaut : 0.

Retourne

str

Le tableau sous forme de chaîne de caractères.

Générer un tableau à partir de l'objet HFCacheInfo.

Passez verbosity=0 pour obtenir un tableau avec une ligne par dépôt, avec les colonnes “repo_id”, “repo_type”, “size_on_disk”, “nb_files”, “last_accessed”, “last_modified”, “refs”, “local_path”.

Passez verbosity=1 pour obtenir un tableau avec une ligne par dépôt et par révision (plusieurs lignes peuvent donc apparaître pour un même dépôt), avec les colonnes “repo_id”, “repo_type”, “revision”, “size_on_disk”, “nb_files”, “last_modified”, “refs”, “local_path”.

Exemple :

>>> from huggingface_hub.utils import scan_cache_dir

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

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

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

CachedRepoInfo

classe huggingface_hub.CachedRepoInfo

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

Paramètres

repo_id (str) — Identifiant du dépôt sur le Hub. Exemple : "google/fleurs".
repo_type (Literal["dataset", "model", "space", "kernel"]) — Type du dépôt mis en cache.
repo_path (Path) — Chemin local vers le dépôt mis en cache.
size_on_disk (int) — Somme des tailles des fichiers blob du dépôt en cache.
nb_files (int) — Nombre total de fichiers blob dans le dépôt mis en cache.
revisions (frozenset[CachedRevisionInfo]) — Ensemble de ~CachedRevisionInfo décrivant toutes les révisions mises en cache dans le dépôt.
last_accessed (float) — Horodatage de la dernière fois qu'un fichier blob du dépôt a été accédé.
last_modified (float) — Horodatage de la dernière modification ou création d'un fichier blob du dépôt.

Structure de données figée contenant des informations sur un dépôt mis en cache.

size_on_disk n’est pas nécessairement la somme des tailles de toutes les révisions en raison des fichiers dupliqués. De plus, seuls les blobs sont pris en compte, et non la taille (négligeable) des dossiers et des liens symboliques.

La fiabilité de last_accessed et last_modified peut dépendre du système d’exploitation utilisé. Voir la documentation Python pour plus de détails.

size_on_disk_str

( )

(property) Somme des tailles des fichiers blob en tant que chaîne de caractères lisible par l'humain.

Exemple : « 42,2 K ».

références

( )

(property) Correspondance entre refs et structures de données de révision.

CachedRevisionInfo

classe huggingface_hub.CachedRevisionInfo

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

Paramètres

commit_hash (str) — Hash de la révision (unique). Exemple : "9338f7b671827df886678df2bdd7cc7b4f36dffd".
snapshot_path (Path) — Chemin vers le répertoire de révision dans le dossier snapshots. Il contient la structure d’arborescence exacte du dépôt sur le Hub.
files — (frozenset[CachedFileInfo]) : Ensemble de ~CachedFileInfo décrivant tous les fichiers contenus dans l'instantané.
refs (frozenset[str]) — Ensemble de refs pointant vers cette révision. Si la révision n'a pas de refs, elle est considérée comme détachée. Exemple : {"main", "2.4.0"} ou {"refs/pr/1"}.
size_on_disk (int) — Somme des tailles des fichiers blob liés par lien symbolique par la révision.
last_modified (float) — Horodatage de la dernière création/modification de la révision.

Structure de données figée contenant des informations sur une révision.

Une révision correspond à un dossier dans le dossier snapshots et est peuplée avec la structure d'arborescence exacte du dépôt sur le Hub, mais ne contient que des liens symboliques. Une révision peut être référencée par 1 ou plusieurs refs ou être « détachée » (aucune ref).

last_accessed ne peut pas être déterminé correctement sur une seule révision, car les fichiers blob sont partagés entre les révisions.

size_on_disk n’est pas nécessairement la somme de toutes les tailles de fichiers en raison de fichiers potentiellement dupliqués. De plus, seuls les blobs sont pris en compte, et non la taille (négligeable) des dossiers et des liens symboliques.

size_on_disk_str

( )

(property) Somme des tailles des fichiers blob en tant que chaîne de caractères lisible par l'humain.

Exemple : « 42,2 K ».

nb_files

( )

(property) Nombre total de fichiers dans la révision.

CachedFileInfo

classe huggingface_hub.CachedFileInfo

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

Paramètres

file_name (str) — Nom du fichier. Exemple : config.json.
file_path (Path) — Chemin du fichier dans le répertoire snapshots. Le chemin du fichier est un lien symbolique pointant vers un blob dans le dossier blobs.
blob_path (Path) — Chemin de l’entrée blob locale au dépôt référencée par file_path. L’entrée blob peut elle-même être un lien symbolique vers le magasin de blobs partagé à l’échelle du cache.
size_on_disk (int) — Taille du fichier blob en octets.
blob_last_accessed (float) — Horodatage de la dernière fois que le fichier blob a été accédé (depuis n'importe quelle révision).
blob_last_modified (float) — Horodatage de la dernière modification ou création du fichier blob.

Structure de données figée contenant des informations sur un fichier mis en cache unique.

La fiabilité de blob_last_accessed et blob_last_modified peut dépendre du système d’exploitation que vous utilisez. Consultez la documentation Python pour plus de détails.

size_on_disk_str

( )

(property) Taille du fichier blob en tant que chaîne de caractères lisible par l'humain.

Exemple : « 42,2 K ».

CachedIncompleteFileInfo

classe huggingface_hub.CachedIncompleteFileInfo

( file_path: Pathsize_on_disk: int )

Paramètres

file_path (Path) — Chemin du fichier .incomplete dans le dossier blobs.
size_on_disk (int) — Taille du fichier partiellement téléchargé, en octets.

Structure de données figée contenant des informations sur un téléchargement incomplet unique.

Les téléchargements interrompus laissent derrière eux des fichiers <cache>/<repo>/blobs/<etag>.incomplete. Ces fichiers ne font partie d'aucune révision validée, ils sont donc affichés séparément par scan_cache_dir().

DeleteCacheStrategy

classe huggingface_hub.DeleteCacheStrategy

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

Paramètres

expected_freed_size (float) — Taille libérée attendue une fois la stratégie exécutée.
blobs (frozenset[Path]) — Ensemble des chemins des fichiers blob à supprimer.
refs (frozenset[Path]) — Ensemble des chemins des fichiers de référence à supprimer.
repos (frozenset[Path]) — Ensemble des chemins complets des dépôts à supprimer.
snapshots (frozenset[Path]) — Ensemble des instantanés à supprimer (répertoire de liens symboliques).
files (frozenset[Path], facultatif) — Ensemble d’entrées de snapshot individuelles à supprimer. Leurs blobs ne sont supprimés que s’ils sont répertoriés dans blobs.
cache_dir (Path ou None) — Répertoire de cache à partir duquel la stratégie a été calculée. Utilisé pour collecter les blobs partagés référencés par les liens symboliques locaux au dépôt supprimés par la suppression.

Structure de données figée contenant la stratégie de suppression des révisions ou fichiers en cache.

Cet objet n’est pas destiné à être instancié de manière programmatique, mais à être retourné par delete_revisions() ou delete_files(). Consultez la documentation pour un exemple d’utilisation.

expected_freed_size_str

( )

(property) Taille attendue qui sera libérée, en tant que chaîne de caractères lisible par un humain.

Exemple : « 42,2 K ».

Exceptions

CorruptedCacheException

classe huggingface_hub.CorruptedCacheException

( )

Exception pour toute structure inattendue dans le système de cache Huggingface.

Update on GitHub

←Discussions et Pull Requests Cartes de dépôt et données de cartes de dépôt→