Aller au contenu
Cercle IA Tech · Open source Un site du réseau Cercle IA Tech

Guide

Télécharger un modèle Hugging Face : commandes, version

Télécharger un modèle ou un jeu de données du Hub : commande hf download, version figée par hash, filtre safetensors, cache et jeton d'accès.

Mis à jour le

Avant de lancer le téléchargement
  1. Ouvrez la fiche du modèle : licence et limites (lire une fiche de modèle).
  2. Lancez --dry-run pour connaître le volume.
  3. Filtrez les fichiers à ceux qui vous servent.
  4. Fixez la version par son hash complet.
  5. Stockez le jeton hors du code, dans le coffre de secrets de votre infrastructure.

Pour télécharger un modèle du Hub, la commande est hf download suivie du nom du dépôt (éditeur/modèle) ; les fichiers sont rangés dans un cache local et la commande affiche leur chemin. Trois réglages évitent les mauvaises surprises : figer la version, choisir les fichiers, gérer le jeton pour les modèles à accès contrôlé. Tout ce qui suit vient du guide officiel de la bibliothèque huggingface_hub et de la page des jetons d'accès, lus le 16/11/2026.

Avant de lancer un téléchargement volumineux, vérifiez que l’exploitation locale répond à un besoin identifié. Les fonctions d’ALMA permettent de comparer ce scénario à celui d’une plateforme ; conservez des critères communs de qualité, de confidentialité et de charge d’administration.

Les trois façons de télécharger

Besoin Commande ou fonction
Un fichier hf download gpt2 config.json ou la fonction Python hf_hub_download
Plusieurs fichiers hf download gpt2 config.json model.safetensors : une barre de progression, puis le dossier du résultat
Tout le dépôt hf download avec le nom seul, ou la fonction Python snapshot_download

Pour un jeu de données, on indique le type de dépôt : la documentation donne la forme hf://datasets/google/fleurs, avec @révision possible après le nom.

Mesurer avant de télécharger

L'option --dry-run liste les fichiers qui seraient téléchargés et leur taille, sans rien enregistrer. L'exemple de la documentation, sur openai-community/gpt2, annonce 11 fichiers sur 26 pour 5,6 Go : un dépôt contient souvent plusieurs copies des poids dans des formats différents. Avant de lancer un téléchargement sur un serveur, c'est la vérification la moins chère.

Ne prendre que les fichiers utiles

Les paramètres allow_patterns et ignore_patterns filtrent par motif. La documentation donne l'exemple d'écarter les fichiers .bin quand on n'utilise que les poids .safetensors. Ce choix a aussi un intérêt de sécurité, expliqué dans sécurité d'un modèle téléchargé : le format safetensors est préférable aux formats qui peuvent exécuter du code au chargement. En ligne de commande, l'option --include "*.json" filtre de la même façon.

Figer la version

Sans précision, vous recevez la dernière version de la branche main, qui peut changer entre deux déploiements. Le paramètre revision accepte :

  • une étiquette (v1.0),
  • une branche,
  • une demande de fusion (refs/pr/3),
  • un hash de commit complet.

Pour un déploiement, le hash est la référence la plus stable : notez-le à côté du nom du dépôt, comme le conseille Hugging Face expliqué, et téléchargez toujours avec lui. Le guide prévient que la forme abrégée à 7 caractères ne fonctionne pas.

Où vont les fichiers

Par défaut, un cache versionné : le chemin retourné est un pointeur vers ce cache, et la documentation demande de ne pas modifier le fichier, au risque de corrompre le cache. Pour un dossier de votre choix, utilisez local_dir : les fichiers y gardent leur arborescence d'origine, et un sous-dossier .cache/huggingface/ conserve les métadonnées pour ne pas retélécharger ce qui est à jour. Le cache lui-même se déplace avec cache_dir ou la variable HF_HOME.

Le jeton pour les modèles à accès contrôlé

Un modèle à accès contrôlé demande d'abord une demande d'accès depuis le navigateur (voir Hugging Face expliqué), puis un jeton dans vos scripts. D'après la page des jetons :

  • trois rôles existent : read (lecture des dépôts auxquels vous avez accès, adapté au téléchargement), write et fine-grained (accès limité à des ressources précises) ;
  • pour une application en production, la documentation recommande uniquement des jetons fine-grained : l'impact d'une fuite est réduit ;
  • un jeton par usage (poste de travail, notebook, serveur d'inférence) permet d'en révoquer un sans toucher aux autres ;
  • une personne de l'organisation qui a obtenu l'accès peut créer un jeton fine-grained en lecture sur ce seul modèle, à donner à l'application ;
  • ne collez jamais un jeton dans un dépôt ou un message : en cas de fuite, il se supprime ou se renouvelle depuis les réglages du compte.

Avant de lancer le téléchargement

  1. Ouvrez la fiche du modèle : licence et limites (lire une fiche de modèle).
  2. Lancez --dry-run pour connaître le volume.
  3. Filtrez les fichiers à ceux qui vous servent.
  4. Fixez la version par son hash complet.
  5. Stockez le jeton hors du code, dans le coffre de secrets de votre infrastructure.

Questions fréquentes

Comment télécharger un modèle Hugging Face en ligne de commande ?

Avec la commande hf download suivie du nom du dépôt, par exemple « hf download gpt2 config.json » pour un fichier, ou le nom seul pour tout le dépôt. La commande affiche le chemin local des fichiers.

Où les fichiers sont-ils enregistrés ?

Par défaut dans un cache, sous ~/.cache/huggingface/hub d'après les exemples de la documentation. On change l'emplacement avec le paramètre cache_dir ou la variable HF_HOME, ou on cible un dossier précis avec local_dir.

Comment être sûr de télécharger toujours la même version ?

Par défaut, la dernière version de la branche main est téléchargée. Le paramètre revision accepte une branche, une étiquette, une demande de fusion ou un hash de commit ; la documentation précise que le hash doit être complet, pas abrégé à 7 caractères.

Sources

Pages consultées pour écrire cet article :

  1. https://alma.iarche.fr/fr/features
  2. https://huggingface.co/docs/huggingface_hub/guides/download
  3. https://huggingface.co/docs/hub/security-tokens

À lire aussi