Hub Python Library documentation

Téléchargement de fichiers

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

Téléchargement de fichiers

Télécharger un fichier unique

hf_hub_download

huggingface_hub.hf_hub_download

< source >

Paramètres

repo_id (str) — Le nom d’un utilisateur ou d’une organisation et le nom d’un dépôt, séparés par un /.
filename (str) — Le nom du fichier dans le dépôt.
subfolder (str, facultatif) — Valeur facultative correspondant à un dossier dans le dépôt du modèle.
repo_type (str, facultatif) — À définir sur "dataset", "space" ou "kernel" si le téléchargement provient d’un dépôt de jeu de données, d’espace ou de noyau, None ou "model" si le téléchargement provient d’un modèle. La valeur par défaut est None.
revision (str, facultatif) — Identifiant de révision Git facultatif, qui peut être un nom de branche, un tag ou un hash de commit.
library_name (str, facultatif) — Le nom de la bibliothèque à laquelle correspond l'objet.
library_version (str, facultatif) — La version de la bibliothèque.
cache_dir (str, Path, facultatif) — Chemin vers le dossier où les fichiers en cache sont stockés.
local_dir (str ou Path, facultatif) — Si fourni, le fichier téléchargé sera placé sous ce répertoire.
user_agent (dict, str, facultatif) — Les informations d’agent utilisateur, sous forme de dictionnaire ou de chaîne de caractères.
force_download (bool, facultatif, valeur par défaut False) — Indique si le fichier doit être téléchargé même s'il existe déjà dans le cache local.
etag_timeout (float, facultatif, par défaut 10) — Lors de la récupération de l'ETag, nombre de secondes à attendre que le serveur envoie des données avant d'abandonner, valeur transmise à httpx2.request.
token (str, bool, facultatif) — Un jeton à utiliser pour le téléchargement.
- Si True, le jeton est lu depuis le dossier de configuration HuggingFace.
- S'il s'agit d'une chaîne de caractères, elle est utilisée en tant que jeton d'authentification.
local_files_only (bool, facultatif, valeur par défaut False) — Si True, évite de télécharger le fichier et renvoie le chemin du fichier en cache local s'il existe.
headers (dict, facultatif) — En-têtes supplémentaires à envoyer avec la requête.
endpoint (str, facultatif) — L’endpoint du Hub auquel envoyer la requête. Par défaut, la valeur de HF_ENDPOINT.
tqdm_class (tqdm, facultatif) — Si fourni, remplace le comportement par défaut de la barre de progression. L’argument transmis doit hériter de tqdm.auto.tqdm ou au moins imiter son comportement. Par défaut, la barre de progression personnalisée de HF est utilisée, et peut être désactivée en définissant la variable d’environnement HF_HUB_DISABLE_PROGRESS_BARS.
dry_run (bool, facultatif, par défaut False) — Si True, effectue une simulation sans réellement télécharger le fichier. Renvoie un objet DryRunFileInfo contenant des informations sur ce qui serait téléchargé.

Retourne

str ou DryRunFileInfo

Si dry_run=False : chemin local du fichier ou, si le réseau est désactivé, dernière version du fichier mise en cache sur le disque.
Si dry_run=True : un objet DryRunFileInfo contenant les informations de téléchargement.

Lève

RepositoryNotFoundError ou RevisionNotFoundError ou ~utils.RemoteEntryNotFoundError ou LocalEntryNotFoundError ou EnvironmentError ou OSError ou ValueError

RepositoryNotFoundError — Si le dépôt à partir duquel le téléchargement doit être effectué n’est pas trouvé. Cela peut être dû au fait qu’il n’existe pas, ou qu’il est défini comme private et que vous n’y avez pas accès.
RevisionNotFoundError — Si la révision à télécharger n'est pas trouvée.
~utils.RemoteEntryNotFoundError — Si le fichier à télécharger ne peut pas être trouvé.
LocalEntryNotFoundError — Si le réseau est désactivé ou indisponible et que le fichier n'est pas trouvé dans le cache.
EnvironmentError — Si token=True mais que le jeton ne peut pas être trouvé.
OSError — Si l'ETag ne peut pas être déterminé.
ValueError — Si la valeur d'un paramètre est invalide.

Télécharger un fichier donné s'il n'est pas déjà présent dans le cache local.

La nouvelle disposition du fichier de cache est la suivante :

Le répertoire de cache contient un sous-dossier par repo_id (namespaced by repo type)
dans chaque dossier de dépôt :
- refs est une liste des dernières paires de révision => commit_hash connues
- blobs contient les blobs de fichiers réels (identifiés par leur git-sha ou sha256, selon qu'il s'agisse ou non de fichiers LFS)
- snapshots contient un sous-dossier par commit, chaque « commit » contenant le sous-ensemble des fichiers résolus à ce commit particulier. Chaque nom de fichier est un lien symbolique vers le blob à ce commit particulier.

[  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

Si local_dir est fourni, la structure de fichiers du dépôt sera répliquée à cet emplacement. Lors de l’utilisation de cette option, le cache_dir ne sera pas utilisé et un dossier .cache/huggingface/ sera créé à la racine de local_dir pour stocker certaines métadonnées liées aux fichiers téléchargés. Bien que ce mécanisme ne soit pas aussi robuste que le système de cache principal, il est optimisé pour récupérer régulièrement la dernière version d’un dépôt.

hf_hub_url

huggingface_hub.hf_hub_url

< source >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )

Paramètres

repo_id (str) — Un nom d’espace de noms (utilisateur ou organisation) et un nom de dépôt séparés par un /.
filename (str) — Le nom du fichier dans le dépôt.
subfolder (str, facultatif) — Valeur facultative correspondant à un dossier dans le dépôt.
repo_type (str, facultatif) — À définir sur "dataset", "space" ou "kernel" si le téléchargement provient d’un dépôt de jeu de données, d’espace ou de noyau, None ou "model" si le téléchargement provient d’un modèle. La valeur par défaut est None.
revision (str, facultatif) — Identifiant de révision Git facultatif, qui peut être un nom de branche, un tag ou un hash de commit.
endpoint (str, facultatif) — L’endpoint du Hub auquel envoyer la requête. Par défaut, la valeur de HF_ENDPOINT.

Construire l’URL d’un fichier à partir des informations fournies.

L'adresse résolue peut être soit une URL hébergée sur huggingface.co, soit un lien vers Cloudfront (un réseau de diffusion de contenu, ou CDN) pour les fichiers volumineux dépassant quelques Mo.

Exemple :

>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'

Remarques :

Cloudfront est répliqué à l’échelle mondiale, ce qui rend les téléchargements beaucoup plus rapides pour l’utilisateur final (et réduit également nos coûts de bande passante).

Cloudfront met en cache les fichiers de manière agressive par défaut (TTL par défaut de 24 heures), mais ce n'est pas un problème ici car nous implémentons un système de versionnement basé sur git sur huggingface.co, ce qui signifie que nous stockons les fichiers sur S3/Cloudfront de manière adressable par contenu (c'est-à-dire que le nom du fichier est son hachage). L'utilisation de noms de fichiers adressables par contenu signifie que le cache ne peut jamais être obsolète.

En ce qui concerne la mise en cache côté client par cette bibliothèque, notre cache est basé sur l’entité tag (ETag) des objets, qui est un identifiant d’une version spécifique d’une ressource [1]_. L’ETag d’un objet est : son git-sha1 s’il est stocké dans git, ou son sha256 s’il est stocké dans git-lfs.

Références :

[1] https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag

Télécharger un instantané du dépôt

huggingface_hub.snapshot_download

< source >

Paramètres

repo_id (str) — Le nom d’un utilisateur ou d’une organisation et le nom d’un dépôt, séparés par un /.
repo_type (str, facultatif) — À définir sur "dataset", "space" ou "kernel" si le téléchargement provient d’un dépôt de jeu de données, d’espace ou de noyau, None ou "model" si le téléchargement provient d’un modèle. La valeur par défaut est None.
revision (str, facultatif) — Identifiant de révision Git facultatif, qui peut être un nom de branche, un tag ou un hash de commit.
cache_dir (str, Path, facultatif) — Chemin vers le dossier où les fichiers en cache sont stockés.
local_dir (str ou Path, facultatif) — Si fourni, les fichiers téléchargés seront placés sous ce répertoire.
library_name (str, facultatif) — Le nom de la bibliothèque à laquelle correspond l'objet.
library_version (str, facultatif) — La version de la bibliothèque.
user_agent (str, dict, facultatif) — Les informations d’agent utilisateur, sous forme de dictionnaire ou de chaîne de caractères.
etag_timeout (float, facultatif, par défaut 10) — Lors de la récupération de l'ETag, nombre de secondes à attendre que le serveur envoie des données avant d'abandonner, valeur transmise à httpx2.request.
force_download (bool, facultatif, valeur par défaut False) — Indique si le fichier doit être téléchargé même s'il existe déjà dans le cache local.
token (str, bool, facultatif) — Un jeton à utiliser pour le téléchargement.
- Si True, le jeton est lu depuis le dossier de configuration HuggingFace.
- S'il s'agit d'une chaîne de caractères, elle est utilisée en tant que jeton d'authentification.
headers (dict, facultatif) — En-têtes supplémentaires à inclure dans la requête. Ces en-têtes ont la priorité sur les autres.
endpoint (str, facultatif) — L’endpoint du Hub auquel envoyer la requête. Par défaut, la valeur de HF_ENDPOINT.
local_files_only (bool, facultatif, valeur par défaut False) — Si True, ne télécharge aucun fichier, même s’ils ne sont pas dans cache_dir ou local_dir.
allow_patterns (list[str] ou str, facultatif) — Si fourni, seuls les fichiers correspondant à au moins un motif sont téléchargés.
ignore_patterns (list[str] ou str, facultatif) — Si fourni, les fichiers correspondant à l’un des motifs ne sont pas téléchargés.
max_workers (int, facultatif) — Nombre de threads concurrents pour télécharger les fichiers (1 thread = 1 téléchargement de fichier). Valeur par défaut : 8.
tqdm_class (tqdm, facultatif) — Si fourni, remplace le comportement par défaut de la barre de progression. L’argument transmis doit hériter de tqdm.auto.tqdm ou au moins imiter son comportement. Notez que tqdm_class n’est pas transmis à chaque téléchargement individuel. Par défaut, la barre de progression personnalisée de HF est utilisée, et peut être désactivée en définissant la variable d’environnement HF_HUB_DISABLE_PROGRESS_BARS.
dry_run (bool, facultatif, par défaut False) — Si True, effectue une simulation sans réellement télécharger les fichiers. Renvoie une liste d'objets DryRunFileInfo contenant des informations sur ce qui serait téléchargé.

Retourne

str ou liste de DryRunFileInfo

Si dry_run=False : chemin local de l'instantané.
Si dry_run=True : une liste d'objets DryRunFileInfo contenant les informations de téléchargement.

Lève

RepositoryNotFoundError ou RevisionNotFoundError ou IncompleteSnapshotError ou EnvironmentError ou OSError ou ValueError

RepositoryNotFoundError — Si le dépôt à partir duquel le téléchargement doit être effectué n’est pas trouvé. Cela peut être dû au fait qu’il n’existe pas ou qu’il est défini comme private et que vous n’y avez pas accès.
RevisionNotFoundError — Si la révision à télécharger n'est pas trouvée.
IncompleteSnapshotError — Si le Hub est inaccessible (hors ligne, problème de connexion ou local_files_only=True) et que le snapshot en cache ne contient pas certains des fichiers demandés.
EnvironmentError — Si token=True et que le jeton ne peut pas être trouvé.
OSError — si l'ETag ne peut pas être déterminé.
ValueError — Si la valeur d'un paramètre est invalide.

Télécharger les fichiers du dépôt.

Téléchargez l’ensemble des fichiers d’un dépôt à la révision spécifiée. Cette opération est utile lorsque vous souhaitez tous les fichiers d’un dépôt, car vous ne savez pas à l’avance lesquels vous seront nécessaires a priori. Tous les fichiers sont imbriqués dans un dossier afin de conserver leur chemin et leur nom de fichier relatifs à ce dossier. Vous pouvez également filtrer les fichiers à télécharger à l’aide de allow_patterns et ignore_patterns.

Une alternative consisterait à cloner le dépôt, mais cela nécessite que git et git-lfs soient installés et correctement configurés. Il est également impossible de filtrer les fichiers à télécharger lors du clonage d'un dépôt à l'aide de git.

Lire l'arborescence du dépôt mise en cache

huggingface_hub.get_cached_repo_tree

< source >

Paramètres

repo_id (str) — Le nom d’un utilisateur ou d’une organisation et le nom d’un dépôt, séparés par un /.
repo_type (str, facultatif) — À définir sur "dataset", "space" ou "kernel" si la liste provient d’un dépôt de jeu de données, d’espace ou de noyau, None ou "model" si la liste provient d’un modèle. La valeur par défaut est None.
revision (str, facultatif) — Identifiant de révision Git facultatif, qui peut être un nom de branche, un tag ou un hash de commit. Par défaut, la branche par défaut est utilisée. Les noms de branche/tag sont résolus en hash de commit à l’aide du cache local (refs/).
cache_dir (str, Path, facultatif) — Chemin du dossier où les fichiers en cache sont stockés. La valeur par défaut est celle de HF_HUB_CACHE.
local_dir (str ou Path, facultatif) — Si fourni, lit la liste de l’arborescence mise en cache par un téléchargement local_dir (depuis local_dir/.cache/huggingface/) au lieu du cache principal. Les révisions de branche/étiquette sont toujours résolues en hachage de commit en utilisant le cache principal (cache_dir).

Retourne

list[RepoFile]

La liste des objets RepoFile mis en cache pour cette révision.

Lève

CachedRepoTreeNotFoundError

CachedRepoTreeNotFoundError — Si aucun arborescence mise en cache n’existe pour la révision demandée (par exemple, le dépôt n’a jamais été téléchargé à cette révision).

Retourne la liste en cache des fichiers d'un dépôt à une révision donnée, sans aucun appel réseau.

La liste d’arborescence est l’ensemble des fichiers (avec leurs métadonnées de téléchargement) d’un dépôt à un commit donné. Elle est créée sur le disque comme effet secondaire de snapshot_download() (voir les fichiers de cache trees/<commit_hash>.json) et sert à éviter les appels réseau lors des téléchargements suivants. Cette fonction expose directement ce cache.

Si vous avez besoin de la liste actuelle de l'arborescence d'un dépôt sur le Hub, utilisez plutôt list_repo_tree().

Exemple :

>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]

Résoudre une révision

Résolvez un nom de branche/étiquette en hachage de commit une seule fois, puis transmettez le résultat pour épingler tous les téléchargements au même commit. Consultez HfApi.resolve_revision() et le guide du système de cache.

ResolvedRevision

classe huggingface_hub.ResolvedRevision

< source >

( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )

Paramètres

initial (str ou None) — La révision initialement demandée par l'utilisateur. Si None, la valeur par défaut de la chaîne est "main".
resolved (str) — Le hash de commit auquel initial se résout.

Une révision git qui a déjà été résolue en hachage de commit.

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 à la révision initialement demandée par l'utilisateur (par exemple "main", "refs/pr/4"), ce qui permet de conserver des URL et des messages d'erreur lisibles, tandis que .resolved contient l'empreinte de commit vers laquelle elle pointe.

Les instances sont construites par HfApi.resolve_revision(), qui met également en cache la correspondance revision -> commit hash dans le cache local (dossier refs/).

Un hash de commit n’a de sens que pour le dépôt auquel il a été résolu, une instance mémorise donc également ce dépôt. Le résoudre à nouveau pour un autre dépôt n’est pas une erreur : la révision initialement demandée est résolue à nouveau (voir HfApi.resolve_revision()).

Exemple :

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

Obtenir les métadonnées d'un fichier

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< source >

Paramètres

url (str) — URL du fichier, par exemple renvoyée par hf_hub_url().
token (str ou bool, facultatif) — Un jeton à utiliser pour le téléchargement.
- Si True, le jeton est lu depuis le dossier de configuration HuggingFace.
- Si False ou None, aucun jeton n'est fourni.
- S'il s'agit d'une chaîne de caractères, elle est utilisée en tant que jeton d'authentification.
timeout (float, facultatif, valeur par défaut 10) — Nombre de secondes à attendre avant d’abandonner si le serveur n’a pas envoyé les métadonnées.
library_name (str, facultatif) — Le nom de la bibliothèque à laquelle correspond l'objet.
library_version (str, facultatif) — La version de la bibliothèque.
user_agent (dict, str, facultatif) — Les informations d’agent utilisateur, sous forme de dictionnaire ou de chaîne de caractères.
headers (dict, facultatif) — En-têtes supplémentaires à envoyer avec la requête.
endpoint (str, facultatif) — Endpoint du Hub. Par défaut, https://huggingface.co.
retry_on_errors (bool, facultatif, valeur par défaut False) — Indique s'il faut réessayer en cas d'erreurs (429, 5xx, dépassement de délai, erreurs réseau). Si False, aucune nouvelle tentative pour un retour rapide au cache local.

Récupérer les métadonnées d'un fichier versionné sur le Hub pour une URL donnée.

HfFileMetadata

classe huggingface_hub.HfFileMetadata

< source >

( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )

Paramètres

commit_hash (str, facultatif) — Le commit_hash associé au fichier.
etag (str, facultatif) — Etag du fichier sur le serveur.
location (str) — Emplacement où télécharger le fichier. Peut être une URL du Hub ou non (CDN).
size (size) — Taille du fichier. Dans le cas d'un fichier LFS, contient la taille du fichier LFS réel, et non celle du pointeur.
xet_file_data (XetFileData, facultatif) — Informations Xet pour le fichier. Ce champ n’est défini que si le fichier est stocké à l’aide du stockage Xet.

Structure de données contenant des informations sur un fichier versionné sur le Hub.

Retourné par get_hf_file_metadata() sur la base d'une URL.

Mise en cache

Les méthodes affichées ci-dessus sont conçues pour fonctionner avec un système de cache qui empêche la rétéléchargement des fichiers. 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 de la mise en cache sur HF.

Update on GitHub

←CLI Mixins & méthodes de sérialisation→