hf-mount : montez les depots Hugging Face comme des systemes de fichiers locaux — sans telechargement

Si vous avez deja attendu 20 minutes qu’un modele de 40 Go se telecharge avant de pouvoir lancer un simple test d’inference, vous comprenez deja le probleme que hf-mount resout.

hf-mount est un nouvel outil open source de Hugging Face qui expose n’importe quel depot ou Bucket du Hub comme un systeme de fichiers local montable. Votre shell voit un repertoire normal. Votre code Python lit des fichiers normaux. Mais rien n’est telecharge tant qu’un octet n’est pas accede — et meme dans ce cas, seulement les octets que vous touchez.

Pas de repertoire de transit. Pas d’attente. Pas de copie.

L’idee centrale

Les workflows Hugging Face traditionnels ressemblent a ceci :

huggingface-cli download openai/gpt-oss-20b
# attendre... attendre... attendre...
python run_inference.py

Avec hf-mount, ca ressemble a ceci :

hf-mount start repo openai/gpt-oss-20b /tmp/model
python run_inference.py   # lit /tmp/model/... a la demande

Le repertoire /tmp/model apparait instantanement. Les fichiers affichent leurs tailles correctes. Vous pouvez faire ls, cat, find et open() comme avec des fichiers locaux. En coulisses, les morceaux sont recuperes depuis le CDN de Hugging Face uniquement lorsque votre processus les lit reellement — et mis en cache localement pour que les lectures repetees soient instantanees.

C’est du chargement paresseux, effectue au niveau du systeme de fichiers OS.

Installation

La methode la plus rapide est le script d’installation :

curl -sSL https://huggingface.co/install/hf-mount | sh

Cela place le binaire dans ~/.local/bin/. Vous pouvez aussi telecharger un binaire manuellement depuis la page des releases GitHub.

Plateformes supportees :

• Linux x86_64 et aarch64
• macOS Apple Silicon

Dependances des backends :

• NFS (recommande) : Aucune dependance supplementaire, fonctionne sans droits root
• FUSE : Necessite fuse3 sous Linux (sudo apt install fuse3) ou macFUSE sous macOS

Authentification

hf-mount lit votre token Hugging Face depuis la variable d’environnement HF_TOKEN :

export HF_TOKEN=hf_votre_token_ici
hf-mount start repo meta-llama/Llama-3-8B /tmp/llama

Ou passez-le directement :

hf-mount start --hf-token $HF_TOKEN repo meta-llama/Llama-3-8B /tmp/llama

Une option --token-file est egalement disponible pour les environnements ou la rotation des credentials est geree en externe.

Monter des depots vs des Buckets

hf-mount supporte deux types de ressources :

Depots (lecture seule)

Les depots de modeles et de jeux de donnees sont montes en lecture seule. Cela couvre la grande majorite des cas d’usage — charger des poids, lire des fragments de jeux de donnees, parcourir des configs.

# Monter un depot de modele
hf-mount start repo openai/gpt-oss-20b /tmp/model

# Monter un depot de jeu de donnees
hf-mount start repo datasets/HuggingFaceFW/fineweb /tmp/fineweb

# Monter seulement un sous-dossier specifique
hf-mount start repo --subfolder en /tmp/fineweb-en

Buckets (lecture-ecriture)

Les Buckets Hugging Face supportent les lectures et les ecritures. Les ecritures sont en mode ajout uniquement par defaut (mode streaming), ce qui fonctionne bien pour la journalisation et la collecte de sorties. Pour les workflows necessitant des modifications en place, utilisez --advanced-writes :

hf-mount start bucket monuser/mon-bucket /tmp/data
hf-mount start --advanced-writes bucket monuser/mon-bucket /tmp/data

Gerer les montages

# Verifier ce qui est actuellement monte
hf-mount status

# Demonter un chemin specifique
hf-mount stop /tmp/model

# Demonter tous les montages actifs
hf-mount stop --all

Comment ca fonctionne en coulisses

hf-mount s’intercale entre votre application et le Hugging Face Hub, traduisant les appels systeme POSIX en requetes API Hub.

Deux backends sont disponibles :

NFS est l’option par defaut et recommandee — elle fonctionne sur n’importe quel systeme sans privileges eleves et offre une excellente compatibilite.

La couche de stockage est construite sur xet-core, le moteur de stockage adresse par contenu de Hugging Face. Les fichiers sont decoupes en morceaux, dedupliques et mis en cache localement (configurable jusqu’a ~10 Go par defaut). Les lectures sequentielles sont accelerees par un tampon de prefetch adaptatif qui ajuste sa fenetre en fonction des schemas d’acces.

Modele de coherence : Les metadonnees sont eventuellement coherentes, avec une fenetre de peremption par defaut de 10 secondes. Les changements distants sont detectes par un processus de polling en arriere-plan (intervalle par defaut : 30 secondes). Ceci est approprie pour les charges de travail ML a lecture intensive mais pas pour les scenarios necessitant une forte coherence.

Support des metadonnees POSIX

Contrairement a certaines solutions de chargement paresseux qui presentent les fichiers comme des blobs opaques, hf-mount supporte un sous-ensemble significatif de metadonnees POSIX :

• chmod, chown (buckets)
• Horodatages (mtime, atime, ctime)
• Liens symboliques
• Traversee de repertoires standard (ls -la, find, tree)

Cela signifie que des outils comme rsync, cp et la plupart des chargeurs de donnees ML fonctionnent sans modification.

Integration Kubernetes

Pour les equipes executant des jobs d’entrainement sur Kubernetes, le hf-csi-driver complementaire expose hf-mount comme un volume CSI (Container Storage Interface). Vous pouvez declarer un depot Hugging Face comme volume dans votre spec de pod et le voir apparaitre a un chemin de montage dans le conteneur — pas de conteneurs init, pas de PVCs, pas d’etapes de telechargement manuelles.

C’est particulierement utile pour les infrastructures d’entrainement a grande echelle ou des dizaines de noeuds ont besoin d’acceder simultanement aux memes poids de modele.

Quand utiliser hf-mount

hf-mount est particulierement adapte pour :

• Inference exploratoire : Tester un modele avant de s’engager dans un telechargement complet
• Echantillonnage de jeux de donnees : Lire 1 000 lignes d’un jeu de donnees de 500 Go sans le telecharger
• Environnements contraints en espace disque : Runners CI, petites VMs, appareils edge
• Pipelines d’entrainement : Charger des fragments de jeux de donnees a la demande sur de nombreux workers
• Navigation dans les depots : Inspecter la structure des fichiers, les configs, les fichiers tokenizer

Ou ce n’est pas le bon outil :

• Charges de travail multi-ecrivains ou plusieurs processus ecrivent dans les memes fichiers simultanement
• I/O aleatoires critiques en termes de latence (le cout du round-trip reseau s’applique)
• Editeurs de texte en mode par defaut (utilisez --advanced-writes pour l’edition en place)
• Scenarios necessitant des garanties de coherence stricte

Notes sur les performances

Le cache local de morceaux est la cle pour rendre cela pratique. Une fois un morceau recupere, les lectures subsequentes touchent le disque local — a pleine vitesse disque. Pour les schemas d’acces sequentiels (lire un fragment de modele du debut a la fin), le tampon de prefetch adaptatif maintient le pipeline plein et minimise le temps d’inactivite reseau.

Pour les schemas d’acces aleatoires (sauter dans un grand jeu de donnees), les performances dependent de votre vitesse de connexion et de la taille des morceaux. Ce sera toujours plus lent que le disque local mais evite completement le cout initial.

La taille du cache peut etre ajustee :

hf-mount start --cache-size-gb 20 repo openai/gpt-oss-20b /tmp/model

Exemple pratique : charger un modele en Python

import subprocess
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# Monter le modele
subprocess.run(["hf-mount", "start", "repo", "meta-llama/Llama-3-8B", "/tmp/llama"], check=True)

# Charger directement depuis le montage — pas d'etape de telechargement separee
tokenizer = AutoTokenizer.from_pretrained("/tmp/llama")
model = AutoModelForCausalLM.from_pretrained("/tmp/llama", torch_dtype=torch.bfloat16)

# Demonter quand c'est termine
subprocess.run(["hf-mount", "stop", "/tmp/llama"])

L’appel from_pretrained lit uniquement les fichiers dont il a besoin (config, tokenizer et les fragments de poids specifiques necessaires). Pour un modele fragmente, cela signifie que seuls les fragments reellement charges en memoire sont transferes sur le reseau.

Conclusion

hf-mount est une solution bien concue pour un point de friction reel dans le workflow ML. L’idee — traiter un depot distant comme un systeme de fichiers — n’est pas nouvelle, mais l’execution ici est solide : backends NFS et FUSE, support des metadonnees POSIX, cache local configurable, integration Kubernetes via CSI, et support lecture-ecriture pour les Buckets.

Si vous travaillez regulierement avec de grands modeles ou jeux de donnees sur Hugging Face, l’installation prend 30 secondes et l’amelioration du workflow est immediate. Commencez avec le backend NFS (pas de root requis), montez un depot que vous telechargez normalement, et executez votre code habituel contre le chemin de montage. Il y a de bonnes chances que ca fonctionne directement.

curl -sSL https://huggingface.co/install/hf-mount | sh
hf-mount start repo <proprietaire>/<depot> /tmp/mnt

Le projet est open source et activement maintenu. Le code source est disponible sur github.com/huggingface/hf-mount.