Intention de recherche : sur un Mac distant ou un runner auto-hébergé, vous voulez trancher vite : faut-il HF_HUB_ENABLE_HF_TRANSFER, comment poser HF_ENDPOINT (miroir ou officiel), où monter HF_HUB_CACHE sans collisions, et comment cléifier le cache CI pour la reprise après coupure. Ce guide est une matrice décisionnelle avec paramètres copiables ; les définitions officielles restent sur la documentation des variables huggingface_hub. Maillage interne : accueil, index du blog ; accélération des tirages et caches : cache modèle OpenClaw par paliers, stratégie cache Git/npm en CI, Python, uv et miroirs PyPI.

Scénarios et checklist des goulots d'étranglement

Avant d'augmenter le parallélisme, vérifiez la chaîne complète : latence vers huggingface.co ou votre miroir, espace disque pour HF_HUB_CACHE et éventuellement HF_XET_CACHE, charge CPU du runner (Xet multiplie les requêtes range), et politique d'accès aux modèles privés (HF_TOKEN dans le coffre CI).

  • Métadonnées lentes : symptômes d'échec ou de fallback alors que le débit brut semble suffisant — souvent HF_HUB_ETAG_TIMEOUT trop court sur liaison transfrontalière.
  • Blobs qui s'arrêtent à mi-parcours : HF_HUB_DOWNLOAD_TIMEOUT trop bas pour des fichiers multi‑Go ; le disque n'est pas toujours en cause.
  • Jobs concurrents sur le même cache : écritures simultanées dans un HF_HUB_CACHE partagé sans sous-répertoires par pipeline → risque de fichiers incomplets ou verrous implicites.
  • Partage NAS / montages exotiques : les symlinks du cache Hub peuvent poser problème ; HF_HUB_DISABLE_SYMLINKS=1 échange de l'espace contre de la robustesse.
Signal observé Cause probable Décision immédiate
Timeout dès la phase HEAD / ETag RTT élevé, proxy inspection Augmenter HF_HUB_ETAG_TIMEOUT ; valider le chemin réseau avant le miroir
Téléchargement blob interrompu Timeout HTTP ou coupure TLS Augmenter HF_HUB_DOWNLOAD_TIMEOUT ; conserver le même HF_HUB_CACHE pour reprise
Débit plat malgré grosse fibre Backend Xet sans mode perf ou concurrence range trop basse HF_XET_HIGH_PERFORMANCE=1 + monter HF_XET_NUM_CONCURRENT_RANGE_GETS par paliers
429 ou limitation de débit Quota côté Hub / miroir Backoff + respect Retry-After ; étaler les pré-tirages ; authentification si applicable

Tableau des variables d'environnement (HF_TRANSFER, point de terminaison, caches, parallélisme)

Les variables doivent être exportées avant import huggingface_hub dans le processus Python qui tire les poids. Pour les pipelines shell, placez-les en tête d'étape ou dans un fichier .env sourcé explicitement.

Variable Rôle Valeur de départ (exemple) Note décisionnelle
HF_HUB_ENABLE_HF_TRANSFER Ancien accélérateur hf_transfer (omettre) Déprécié quand le stockage Hub est servi via Xet ; préférer hf-xet et les variables HF_XET_*
HF_ENDPOINT Base URL de l'API Hub compatible https://huggingface.co ou URL miroir approuvée Vérifier conformité et parité des révisions ; inclure le host dans la clé de cache
HF_HOME Racine tokens + caches par défaut ex. $HOME/Library/Caches/huggingface-ci sur macOS Isolez par compte de service CI pour éviter les fuites entre projets
HF_HUB_CACHE Répertoire des snapshots / blobs Hub $HF_HOME/hub explicite Doit correspondre au path de l'action cache (GitHub, GitLab, etc.)
HF_XET_CACHE Cache des chunks Xet (si utilisé) Sous-répertoire dédié sur SSD rapide Dimensionnez en plus de HF_HUB_CACHE pour les très gros modèles
HF_XET_HIGH_PERFORMANCE Mode performant côté client Xet 1 sur nœud dédié avec marge CPU Sur runner partagé, mesurer l'impact avant de laisser activé en permanence
HF_XET_NUM_CONCURRENT_RANGE_GETS Parallélisme des requêtes HTTP range 8 → 16 → 32 RTT élevé : monter avec prudence ; trop haut peut saturer le proxy
HF_HUB_DOWNLOAD_TIMEOUT Timeout par fichier (secondes) 120–600 Ajuster à la taille du plus gros shard, pas à la moyenne
HF_HUB_ETAG_TIMEOUT Timeout métadonnées / ETag 30–120 Évite les faux négatifs « réseau mort » sur liaisons longues
HF_HUB_OFFLINE Forcer l'usage du cache local 1 en smoke test uniquement Valide que le job n'effectue plus d'appels HTTP inattendus
HF_TOKEN Jeton pour dépôts gated Secret CI Ne jamais committer ; aligner les droits lecture sur le miroir si utilisé 
# À exécuter avant import huggingface_hub / transformers
export HF_HOME="${HF_HOME:-$HOME/Library/Caches/huggingface-ci}"
export HF_HUB_CACHE="${HF_HUB_CACHE:-$HF_HOME/hub}"
# export HF_ENDPOINT="https://huggingface.co"
export HF_HUB_ETAG_TIMEOUT=60
export HF_HUB_DOWNLOAD_TIMEOUT=300
export HF_XET_HIGH_PERFORMANCE=1
export HF_XET_NUM_CONCURRENT_RANGE_GETS=16
# export HF_TOKEN="$(cat "$HF_TOKEN_FILE")"
python -c "import huggingface_hub; print('hub', huggingface_hub.__version__)"

Reprise après coupure et conception des clés de cache CI

huggingface_hub tente en général de reprendre les téléchargements partiels présents sous HF_HUB_CACHE. En cas d'échec intermittent, ne videz pas tout le cache : relancez d'abord avec les mêmes variables et le même chemin. Ne purgez le sous-dossier du modèle qu'après avoir identifié une corruption (checksum, erreurs répétées sur un seul blob).

Formule de clé de cache (exemple GitHub Actions) : préfixe stable + segments qui cassent le cache quand la sémantique change :

huggingface-${{ runner.os }}-${{ hashFiles('requirements.txt','pyproject.toml') }}-\
${{ env.HF_ENDPOINT_SLUG }}-${{ env.MODEL_REVISION }}-\
symlinks-${{ env.HF_HUB_DISABLE_SYMLINKS:-0 }}

Remplacez HF_ENDPOINT_SLUG par un identifiant court dérivé du host (ex. official vs mirror-east). MODEL_REVISION doit être le SHA de commit Hub ou une étiquette immuable versionnée dans le dépôt. Si vous changez de miroir, changez de segment ou de racine HF_HUB_CACHE pour éviter des blobs incohérents entre deux origines.

Pour les pools partagés, préférez un répertoire de cache par workspace de pipeline ou un job de pré-tirage sérialisé qui alimente ensuite des jobs parallèles en lecture seule.

FAQ : échecs, nouvelles tentatives et seuils de timeout

Faut-il encore définir HF_HUB_ENABLE_HF_TRANSFER=1 en 2026 ?

Non sur les stacks à jour derrière Xet : ce drapeau est historique. Installez hf-xet, fixez HF_XET_HIGH_PERFORMANCE et HF_XET_NUM_CONCURRENT_RANGE_GETS, puis mesurez. Réservez hf_transfer aux reproductions d'incidents sur d'anciennes versions.

Quelles valeurs cibles pour HF_HUB_DOWNLOAD_TIMEOUT et HF_HUB_ETAG_TIMEOUT ?

Commencez par 60 s / 300 s (ETag / download) sur liaisons moyennes ; montez à 120 s / 600 s si les journaux montrent encore des timeouts. Couplez cela avec un timeout de job CI supérieur à la durée du plus gros artefact attendu.

Comment retry sans déclencher une tempête 429 ?

Backoff exponentiel avec jitter (par ex. 2n secondes plafonnées à 120 s), limite globale de tentatives (3–5), et respect explicite de Retry-After. Étalez les pré-tirages des grosses révisions sur des créneaux creux.

Comment prouver que le cache suffit pour un test d'intégration ?

Après un run réussi, relancez une étape avec HF_HUB_OFFLINE=1 : si l'étape échoue, il reste des appels réseau implicites ou des fichiers manquants dans HF_HUB_CACHE.

Synthèse

En 2026, la décision ne se résume pas à « activer HF_TRANSFER » : il faut aligner Xet (HF_XET_HIGH_PERFORMANCE, HF_XET_NUM_CONCURRENT_RANGE_GETS), calibrer les timeouts (HF_HUB_ETAG_TIMEOUT, HF_HUB_DOWNLOAD_TIMEOUT), figer HF_ENDPOINT et les chemins de cache, et cléifier le cache CI avec la révision du modèle et l'origine des blobs. Un Mac distant proche d'une sortie réseau stable et d'un SSD rapide réduit les allers-retours transfrontaliers et rend ces réglages payants sur la durée — surtout si vous enchaînez entraînement léger, évaluation et pipelines OpenClaw sur le même hôte.

Poursuivre sans connexion : accueil, tarifs, achat, centre d'aide, blog technique.

Traitez HF_HUB_CACHE comme un contrat de reproductibilité : mêmes variables, même clé, même révision — puis ajustez le parallélisme Xet et les timeouts à partir de métriques réelles, pas de superstitions sur les anciens drapeaux.

Louer un Mac distant pour CI et tirages HF

Apple Silicon, disque rapide et SSH : adaptez vos runners aux gros poids et aux jobs répétés. Parcourez l'accueil, les offres et le centre d'aide sans vous connecter.

Accueil Tarifs & achat Centre d'aide