Télécharger des fichiers depuis le Hub

La bibliothèque huggingface_hub fournit des fonctions pour télécharger des fichiers depuis les dépôts stockés sur le Hub. Vous pouvez utiliser ces fonctions de manière indépendante ou les intégrer dans votre propre bibliothèque, ce qui facilite l’interaction de vos utilisateurs avec le Hub. Ce guide vous montre comment :

• Télécharger et mettre en cache un fichier unique.
• Télécharger et mettre en cache un dépôt entier.
• Télécharger des fichiers dans un dossier local.

Télécharger un fichier unique

La fonction hf_hub_download() est la fonction principale pour télécharger des fichiers depuis le Hub. Elle télécharge le fichier distant, le met en cache sur le disque (de manière sensible aux versions) et renvoie son chemin de fichier local.

Le chemin de fichier renvoyé est un pointeur vers le cache local HF. Il est donc important de ne pas modifier le fichier afin d'éviter d'endommager le cache. Si vous souhaitez en savoir plus sur la manière dont les fichiers sont mis en cache, veuillez consulter notre guide de mise en cache.

À partir de la dernière version

Sélectionnez le fichier à télécharger à l’aide des paramètres repo_id, repo_type et filename. Par défaut, le fichier est considéré comme faisant partie d’un dépôt model.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

# Download from a dataset
>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset")
'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py'

À partir d'une version spécifique

Par défaut, la dernière version de la branche main est téléchargée. Cependant, dans certains cas, vous souhaitez télécharger un fichier à une version particulière (par exemple depuis une branche spécifique, une PR, un tag ou un hash de commit). Pour ce faire, utilisez le paramètre revision :

# Download from the `v1.0` tag
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")

# Download from the `test-branch` branch
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")

# Download from Pull Request #3
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3")

# Download from a specific commit hash
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a")

Remarque : Lors de l'utilisation du hachage de commit, il doit s'agir du hachage de longueur complète et non d'un hachage de commit de 7 caractères.

Construire une URL de téléchargement

Si vous souhaitez construire l’URL utilisée pour télécharger un fichier depuis un dépôt, vous pouvez utiliser hf_hub_url() qui renvoie une URL. Notez qu’elle est utilisée en interne par hf_hub_download().

Télécharger un dépôt entier

snapshot_download() télécharge un dépôt entier à une révision donnée. Il utilise en interne hf_hub_download(), ce qui signifie que tous les fichiers téléchargés sont également mis en cache sur votre disque local. Les téléchargements sont effectués de manière concurrente pour accélérer le processus.

Pour télécharger un dépôt entier, il suffit de passer repo_id et repo_type :

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

# Or from a dataset
>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset")
'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34'

snapshot_download() télécharge la dernière révision par défaut. Si vous souhaitez une révision spécifique du dépôt, utilisez le paramètre revision :

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")

Filtrer les fichiers à télécharger

snapshot_download() offre un moyen simple de télécharger un dépôt. Cependant, vous ne souhaitez pas toujours télécharger l’intégralité du contenu d’un dépôt. Par exemple, vous pouvez vouloir éviter de télécharger tous les fichiers .bin si vous savez que vous n’utiliserez que les poids .safetensors. Vous pouvez le faire à l’aide des paramètres allow_patterns et ignore_patterns.

Ces paramètres acceptent soit un motif unique, soit une liste de motifs. Les motifs sont des jokers standard (motifs glob) tels que documentés ici. L’appariement des motifs est basé sur fnmatch.

Par exemple, vous pouvez utiliser allow_patterns pour ne télécharger que les fichiers de configuration JSON :

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")

En revanche, ignore_patterns permet d'exclure certains fichiers du téléchargement. L'exemple suivant ignore les extensions de fichiers .msgpack et .h5 :

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])

Enfin, vous pouvez combiner les deux pour filtrer précisément votre téléchargement. Voici un exemple pour télécharger tous les fichiers json et markdown à l'exception de vocab.json.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")

Télécharger le(s) fichier(s) dans un dossier local

Par défaut, nous recommandons d'utiliser le système de cache pour télécharger les fichiers depuis le Hub. Vous pouvez spécifier un emplacement de cache personnalisé à l'aide du paramètre cache_dir dans hf_hub_download() et snapshot_download(), ou en définissant la variable d'environnement HF_HOME.

Cependant, si vous devez télécharger des fichiers dans un dossier spécifique, vous pouvez passer un paramètre local_dir à la fonction de téléchargement. Cela est utile pour obtenir un flux de travail plus proche de ce que propose la commande git. Les fichiers téléchargés conserveront leur structure de fichiers d'origine au sein du dossier spécifié. Par exemple, si filename="data/train.csv" et local_dir="path/to/folder", le chemin d'accès résultant sera "path/to/folder/data/train.csv".

Un dossier .cache/huggingface/ est créé à la racine de votre répertoire local, contenant les métadonnées des fichiers téléchargés. Cela évite de retélécharger les fichiers s'ils sont déjà à jour. Si les métadonnées ont changé, la nouvelle version du fichier est téléchargée. Cela optimise le local_dir pour ne récupérer que les dernières modifications.

Une fois le téléchargement terminé, vous pouvez supprimer en toute sécurité le dossier .cache/huggingface/ si vous n'en avez plus besoin. Toutefois, sachez que la réexécution de votre script sans ce dossier peut entraîner des temps de récupération plus longs, car les métadonnées seront perdues. Vos données locales resteront intactes et inchangées.

Ne vous inquiétez pas du dossier .cache/huggingface/ lors de l’envoi de modifications sur le Hub ! Ce dossier est automatiquement ignoré par git et par upload_folder().

Télécharger depuis le CLI

Vous pouvez utiliser la commande hf download depuis le terminal pour télécharger directement des fichiers depuis le Hub. En interne, elle utilise les mêmes fonctions d’aide hf_hub_download() et snapshot_download() décrites ci-dessus et affiche le chemin renvoyé dans le terminal.

>>> hf download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

Vous pouvez télécharger plusieurs fichiers à la fois, ce qui affiche une barre de progression et renvoie le chemin de l'instantané dans lequel les fichiers sont situés :

>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

Vous pouvez également pointer vers le dépôt (et éventuellement une révision et un fichier) à l’aide d’un seul URI hf://. L’URI suit la grammaire hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (voir la référence des URI HF pour la syntaxe complète) et remplace les options --repo-type et --revision, qui ne peuvent pas être définies en même temps :

# Download a single file from a dataset at a given revision
>>> hf download hf://datasets/google/fleurs@refs/pr/1/fleurs.py

# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/google/fleurs/data/

# Download an entire repo
>>> hf download hf://datasets/google/fleurs

Pour plus de détails sur la commande de téléchargement CLI, veuillez consulter le guide CLI.

Mode de simulation

Dans certains cas, vous souhaitez vérifier quels fichiers seraient téléchargés avant de procéder au téléchargement. Vous pouvez le faire à l'aide du paramètre --dry-run. Il répertorie tous les fichiers à télécharger dans le dépôt et vérifie s'ils ont déjà été téléchargés. Cela donne une idée du nombre de fichiers à télécharger et de leur taille.

Voici un exemple, vérifiant sur un seul fichier :

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 1 files (out of 1) totalling 655.2M
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx 655.2M

Et si le fichier est déjà mis en cache :

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 0 files (out of 1) totalling 0.0.
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx -

Vous pouvez également exécuter une simulation sur un dépôt entier :

>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00,  6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File                              Bytes to download
--------------------------------- -----------------
.gitattributes                    -
64-8bits.tflite                   125.2M
64-fp16.tflite                    248.3M
64.tflite                         495.8M
README.md                         -
config.json                       -
flax_model.msgpack                497.8M
generation_config.json            -
merges.txt                        -
model.safetensors                 548.1M
onnx/config.json                  -
onnx/decoder_model.onnx           653.7M
onnx/decoder_model_merged.onnx    655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json       -
onnx/merges.txt                   -
onnx/special_tokens_map.json      -
onnx/tokenizer.json               -
onnx/tokenizer_config.json        -
onnx/vocab.json                   -
pytorch_model.bin                 548.1M
rust_model.ot                     702.5M
tf_model.h5                       497.9M
tokenizer.json                    -
tokenizer_config.json             -
vocab.json                        -

Et avec le filtrage des fichiers :

>>> hf download openai-community/gpt2 --include "*.json"  --dry-run
[dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s]
[dry-run] Will download 0 files (out of 11) totalling 0.0.
File                         Bytes to download
---------------------------- -----------------
config.json                  -
generation_config.json       -
onnx/config.json             -
onnx/generation_config.json  -
onnx/special_tokens_map.json -
onnx/tokenizer.json          -
onnx/tokenizer_config.json   -
onnx/vocab.json              -
tokenizer.json               -
tokenizer_config.json        -
vocab.json                   -

Enfin, vous pouvez également effectuer une simulation de manière programmatique en passant dry_run=True à hf_hub_download() et snapshot_download(). Cela renverra un DryRunFileInfo (respectivement une liste de DryRunFileInfo) contenant, pour chaque fichier, son hash de commit, son nom et sa taille, ainsi que l'indication de savoir si le fichier est en cache et s'il serait téléchargé. En pratique, le fichier sera téléchargé s'il n'est pas en cache ou si force_download=True est passé.

Téléchargements plus rapides

Profitez de téléchargements plus rapides grâce à hf_xet, le binding Python de la bibliothèque xet-core qui permet la déduplication par blocs pour des téléchargements et des téléversements plus rapides. hf_xet s’intègre parfaitement à huggingface_hub, mais utilise la bibliothèque Rust xet-core et le stockage Xet au lieu de LFS.

hf_xet utilise le système de stockage Xet, qui découpe les fichiers en chunks immuables, stocke des collections de ces chunks (appelés blocks ou xorbs) à distance et les récupère pour réassembler le fichier à la demande. Lors du téléchargement, après avoir confirmé que l’utilisateur est autorisé à accéder aux fichiers, hf_xet interroge le service de contenu adressable (CAS) de Xet avec l’empreinte SHA256 LFS de ce fichier afin de recevoir les métadonnées de reconstruction (les plages au sein des xorbs) nécessaires pour assembler ces fichiers, ainsi que des URL présignées pour télécharger directement les xorbs. Ensuite, hf_xet télécharge efficacement les plages de xorbs nécessaires et écrit les fichiers sur le disque.

Pour l'activer, il suffit d'installer la dernière version de huggingface_hub :

pip install -U "huggingface_hub"

À partir de huggingface_hub 0.32.0, cela installera également hf_xet.

Toutes les autres API de huggingface_hub continueront de fonctionner sans aucune modification. Pour en savoir plus sur les avantages du stockage Xet et de hf_xet, consultez cette section.

Remarque : hf_transfer était auparavant utilisé avec le backend de stockage LFS et est désormais obsolète ; utilisez hf_xet à la place.