hfdownloader : télécharger des modèles HuggingFace sans passer par Python

Le vide que comble un binaire Go

huggingface_hub fait bien son travail, mais il suppose un interpréteur Python, des dépendances installées et un environnement réseau qui accepte les connexions sortantes standard. Sur un serveur d'inférence sans Python, dans un conteneur minimal, ou derrière un pare-feu d'entreprise qui n'autorise que SOCKS5, cette hypothèse tombe. hfdownloader est un binaire Go unique, décrit dans le README comme distribué via un script d'installation qui, par défaut, place l'exécutable dans ~/.local/bin sans sudo. Le public visé est donc celui qui prépare des machines pour llama.cpp, des serveurs d'inférence, ou des postes où l'on veut récupérer un dépôt sans installer tout un écosystème scientifique. Le README insiste aussi sur un point qui n'est pas cosmétique : les fichiers vont dans le cache HuggingFace standard, donc transformers, diffusers et huggingface_hub les retrouvent sans configuration supplémentaire. C'est la contrainte qui rend l'outil utilisable en remplacement plutôt qu'en complément.

Deux couches d'écriture dans le cache

Le point le plus intéressant du projet, et le plus facile à rater, est le mode de stockage par défaut. Le README le décrit comme un cache HuggingFace à double couche : d'un côté l'arborescence attendue par les bibliothèques Python, de l'autre des chemins lisibles sous ~/.cache/huggingface/models/ pour parcourir les fichiers à la main. Un second mode existe, présenté comme tout aussi supporté, sans que la documentation fournie détaille sa structure. Cette dualité a un coût : deux représentations du même contenu peuvent dériver, et la question de savoir laquelle fait foi en cas de reprise ou de vérification n'est pas tranchée dans les extraits disponibles. Sur le plan du transport, le mécanisme est explicite : jusqu'à 16 connexions parallèles par fichier en téléchargement chunké, et jusqu'à 8 fichiers simultanés. Les valeurs par défaut sont plus prudentes, avec -c à 8 connexions par fichier et --max-active à 3 fichiers. La reprise est automatique : relancer la même commande reprend un transfert interrompu. Rien dans le matériel fourni ne permet de dire comment les chunks sont réconciliés après un arrêt brutal, ni si un fichier partiellement écrit est visible par les bibliothèques Python avant vérification.

L'analyseur, ou pourquoi -i change l'usage

La commande analyze est ce qui distingue l'outil d'un simple client HTTP. Sans option, elle produit du texte ou du JSON, ce qui la rend scriptable. Avec -i, elle ouvre un sélecteur interactif : navigation au clavier, espace pour cocher, notation en étoiles, estimation de RAM, badge Recommended sur Q4_K_M, total de taille mis à jour à chaque sélection, et touche c pour copier la commande de téléchargement générée. L'analyse ne se limite pas aux GGUF. Le README liste la détection automatique pour les modèles Transformers (architecture, paramètres, longueur de contexte, taille du vocabulaire), les pipelines Diffusers (type, composants, variantes fp16 et bf16), les LoRA (modèle de base, rang, alpha, modules cibles), les formats GPTQ et AWQ (bits, group size, VRAM estimée) et les datasets (formats, configs, splits, tailles). Pour Stable Diffusion, un sélecteur de composants permet de ne garder que unet, vae ou text_encoder et de sauter le reste. C'est un vrai gain sur les dépôts multi-branches, où le README donne l'exemple de CompVis/stable-diffusion-v1-4 avec ses branches fp16, onnx et flax. Les estimations de RAM et de VRAM restent des estimations : le README ne documente pas la méthode de calcul, et il faut les traiter comme un ordre de grandeur, pas comme une garantie de tenue en mémoire.

Filtres intégrés et vérification

Le filtrage se fait dans l'argument lui-même, ce qui évite d'empiler des options. hfdownloader download TheBloke/Mistral-7B-Instruct-v0.2-GGUF:q4_k_m ne récupère qu'une quantification, et la syntaxe accepte plusieurs valeurs séparées par des virgules, par exemple q4_k_m,q5_k_m. Les flags -F et -E font la même chose sous forme de motifs d'inclusion et d'exclusion, avec un exemple qui combine -F q4_k_m et -E ".md,fp16". La révision se choisit avec -b, dont la valeur par défaut est main et qui accepte une branche, un tag ou un commit. Deux options méritent d'être connues avant de lancer un gros transfert : --dry-run affiche ce qui serait téléchargé sans rien écrire, et --verify sha256 force une vérification stricte. Le README ne précise pas si cette vérification s'applique aux fichiers du Hub qui publient des empreintes, ni ce qui se passe quand aucune empreinte n'est disponible. Sur un dépôt communautaire sans métadonnées complètes, c'est le genre de détail qui décide si l'option est utilisable en production.

Proxy, authentification et interface web

Le support proxy est présenté comme complet : SOCKS5, authentification et règles de contournement par CIDR. L'exemple du README est hfdownloader download meta-llama/Llama-2-7b --proxy socks5://localhost:1080. C'est le cas d'usage qui justifie souvent l'adoption, parce que les clients Python gèrent moins bien les proxys authentifiés. À côté de la ligne de commande, le binaire embarque un serveur web via hfdownloader serve, avec une option d'authentification basique : --auth-user admin --auth-pass secret. Le README ne décrit ni le périmètre exact de cette interface, ni les précautions à prendre si elle est exposée au-delà de localhost, ni si l'authentification protège les téléchargements ou seulement l'affichage. Pour un usage sur un réseau partagé, c'est une zone à vérifier dans le code avant de lancer serve sur une interface publique. Le script d'installation, lui, s'exécute via bash <(curl -sSL https://g.bodaay.io/hfd), ce qui suppose de faire confiance au domaine et à la chaîne TLS. Un binaire Go publié en release serait une alternative plus vérifiable, mais le README met en avant cette méthode.

Ce que l'outil ne fait pas

hfdownloader ne remplace pas un gestionnaire de versions de modèles, et il ne fait pas de synchronisation bidirectionnelle. Le README mentionne une section Mirror Sync dans sa table des matières, mais le contenu correspondant n'apparaît pas dans l'extrait fourni : impossible de dire ce que la fonctionnalité couvre réellement. Autre limite : l'outil écrit dans un cache partagé avec les bibliothèques Python. Si un pipeline existant dépend d'une organisation précise de ce cache, ou si plusieurs outils écrivent en parallèle dans le même répertoire, la coexistence n'est pas documentée. Le mode par défaut à double couche rend ce risque plus concret qu'avec un client qui n'écrit qu'une seule arborescence. Enfin, sur les très gros dépôts, la parallélisation agressive n'est pas neutre : 16 connexions par fichier multipliées par plusieurs fichiers actifs peuvent saturer un lien partagé ou déclencher une limitation côté serveur. Le README donne les valeurs par défaut sans discuter ce point.

Face à huggingface-cli

L'alternative directe est huggingface-cli, fourni par huggingface_hub. La différence n'est pas une question de vitesse mais de dépendances et de contrôle. huggingface-cli vit dans l'écosystème Python, s'installe avec pip, et hérite de la configuration de l'environnement Python courant. hfdownloader est un binaire autonome, avec ses propres options de proxy et de filtrage, et son analyseur interactif n'a pas d'équivalent dans huggingface-cli : le picker GGUF avec notation, estimation de RAM et badge Recommended est propre à ce projet. En contrepartie, huggingface-cli bénéficie d'une intégration native avec le Hub, d'une gestion des jetons et des dépôts privés documentée publiquement, et d'une base d'utilisateurs qui remonte les régressions. Le README de hfdownloader ne détaille pas la gestion des dépôts privés ni l'authentification par jeton, ce qui est un manque pour quiconque travaille sur des modèles restreints. Pour un dépôt public et une machine sans Python, hfdownloader est plus léger. Pour un dépôt privé dans un pipeline Python existant, huggingface-cli reste le chemin court.

Maintenance, licence et coût de mise à jour

Le projet est actif, avec trois versions publiées entre mai et juin 2026 selon les données du dépôt, et une licence Apache-2.0. Cette licence autorise l'usage commercial, la modification et la redistribution, à condition de conserver les mentions de copyright et le texte de licence, et elle inclut une clause de brevets. Elle ne donne aucune garantie : le logiciel est fourni en l'état, ce qui compte pour un outil qui écrit dans un cache partagé par d'autres programmes. Le coût de mise à jour est faible côté binaire, puisqu'il s'agit d'un exécutable unique remplaçable. Il est plus élevé côté données : une nouvelle version qui change le mode de stockage par défaut, ou la structure du cache à double couche, peut laisser des fichiers orphelins dans ~/.cache/huggingface/. Le README affirme que les deux modes de stockage sont supportés et qu'aucun ne disparaîtra, ce qui limite ce risque, mais cette promesse n'est pas accompagnée d'une procédure de migration. Avant de mettre à jour sur une machine qui sert de cache partagé, la vérification utile est de comparer l'arborescence produite par l'ancienne et la nouvelle version sur un petit dépôt, avec --dry-run puis un téléchargement réel.

Conclusion éditoriale

hfdownloader convient à ceux qui rapatrient des dépôts volumineux depuis des machines non-Python, derrière un proxy d'entreprise, ou qui veulent choisir une quantification GGUF sans ouvrir une session Python. Ceux qui ont déjà un pipeline huggingface_hub fonctionnel et un cache propre n'y gagneront pas grand-chose. Avant d'adopter, vérifier deux points dans le dépôt : la correspondance exacte entre l'arborescence écrite et celle attendue par les bibliothèques Python, et le comportement de la reprise après une interruption au milieu d'un fichier chunké.

Sources officielles

1. bodaay/HuggingFaceModelDownloader on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases