Utilisation du stockage Xet

Python

Pour accéder à une version de huggingface_hub compatible avec Xet, installez simplement la dernière version :

pip install -U huggingface_hub

À partir de huggingface_hub 0.32.0, cela installera également hf_xet. Le package hf_xet intègre huggingface_hub avec xet-core, le client Rust pour le backend Xet.

Si vous utilisez les bibliothèques transformers ou datasets, elles utilisent déjà huggingface_hub. Tant que la version de huggingface_hub est >= 0.32.0, aucune action supplémentaire n’est nécessaire.

Lorsque des versions de huggingface_hub >= 0.30.0 et < 0.32.0 sont installées, hf_xet doit être installé explicitement :

pip install -U hf-xet

Et c’est tout ! Vous bénéficiez désormais de la déduplication Xet pour les téléversements comme pour les téléchargements. Les membres de l’équipe utilisant une version de huggingface_hub < 0.30.0 pourront toujours téléverser et télécharger des dépôts grâce à la compatibilité ascendante fournie par le pont LFS.

Pour consulter des documents d'utilisation plus détaillés, reportez-vous à la documentation de huggingface_hub pour :

• Téléverser
• Télécharger
• Gérer le cache hf_xet

Git

Les utilisateurs de Git peuvent profiter des avantages de Xet en téléchargeant et en installant l’extension Git Xet. Une fois installée, il suffit d’utiliser les flux de travail standard pour gérer les dépôts du Hub avec Git - aucune modification supplémentaire n’est nécessaire.

Prérequis

Installez Git et Git LFS.

Installer sur macOS ou Linux (amd64 ou aarch64)

Installez à l'aide d'un script d'installation avec la commande suivante dans votre terminal (nécessite curl et unzip) :

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/huggingface/xet-core/refs/heads/main/git_xet/install.sh | sh

Sinon, installez à l'aide de Homebrew :

brew install git-xet
git xet install

Pour vérifier l'installation, exécutez :

git xet --version

Windows (amd64)

En utilisant winget :

winget install git-xet

À l'aide d'un installateur :

• Téléchargez git-xet-windows-installer-x86_64.zip (disponible ici) et décompressez-le.
• Exécutez le fichier d'installation msi et suivez les instructions.

Installation manuelle :

• Téléchargez git-xet-windows-x86_64.zip (disponible ici) et décompressez-le.
• Placez le fichier git-xet.exe extrait dans un répertoire du PATH.
• Exécutez git xet install dans un terminal.

Pour vérifier l'installation, exécutez :

git xet --version

Utilisation de Git Xet

Une fois installé sur votre plateforme, l’utilisation de Git Xet est aussi simple que le suivi des flux de travail Git standard du Hub.

Assurez-vous que toutes les prérequis sont installés et configurés, suivez les instructions de configuration pour travailler avec les dépôts sur le Hub, puis engagez vos modifications et push vers le Hub :

# Create any files you like! Then...
git add .
git commit -m "Uploading new models"  # You can choose any descriptive message
git push

Sous le capot, le protocole Xet est appelé pour téléverser les fichiers volumineux directement vers le stockage Xet, augmentant les vitesses de téléversement grâce à la déduplication au niveau des blocs.

Désinstallation sur macOS ou Linux

À l'aide de Homebrew :

git xet uninstall
brew uninstall git-xet

Si vous avez utilisé le script d’installation (pour MacOS ou Linux), exécutez la commande suivante dans votre terminal :

git xet uninstall
sudo rm $(which git-xet)

Désinstallation sur Windows

Si vous avez utilisé winget :

winget uninstall git-xet

Si vous avez utilisé l'installateur :

• Accédez à Paramètres -> Applications -> Applications installées
• Rechercher « Git-Xet ».
• Sélectionnez l’option « Désinstaller » disponible dans le menu contextuel.

Si vous avez installé manuellement :

• Exécutez git xet uninstall dans un terminal.
• Supprimez le fichier git-xet.exe de l'emplacement où il a été initialement placé.

Recommandations

Xet s’intègre parfaitement à tous les flux de travail du Hub. Toutefois, il existe quelques étapes que vous pouvez envisager pour tirer le meilleur parti du stockage Xet.

Lors de l’envoi ou du téléchargement avec Python :

• Vérifiez que hf_xet est installé : bien que Xet reste rétrocompatible avec les clients legacy optimisés pour Git LFS, l’intégration de hf_xet avec huggingface_hub offre des performances optimales basées sur les chunks et une itération plus rapide sur les gros fichiers.
• La concurrence adaptative est activée par défaut : hf_xet ajuste automatiquement le nombre de flux de transfert parallèles en fonction des conditions réseau en temps réel — aucune configuration n'est requise. Les paramètres par défaut satureront la plupart des chemins réseau sans aucun réglage.
• Les tampons de téléchargement s’adaptent à la mémoire système : à partir de hf_xet 1.7.0, la taille des tampons de téléchargement est déterminée par la mémoire disponible pour hf_xet, y compris les limites de mémoire des conteneurs. Les petits conteneurs utilisent moins de mémoire pour les téléchargements et les grandes machines en utilisent davantage, sans aucun réglage nécessaire. Voir Tampons de téléchargement.
• Réglages avancés : Pour un contrôle fin, HF_XET_FIXED_DOWNLOAD_CONCURRENCY et HF_XET_FIXED_UPLOAD_CONCURRENCY permettent de fixer la concurrence à une valeur donnée, en contournant le contrôleur adaptatif. Consultez les variables d’environnement de hf_xet pour la liste complète des options.

Lors de la mise en ligne ou du téléchargement dans Git ou Python :

• Exploiter des commits fréquents et incrémentiels : la déduplication au niveau des blocs de Xet permet d’effectuer des mises à jour incrémentielles de modèles ou de jeux de données en toute sécurité. Seuls les blocs modifiés sont téléversés, ce qui rend les commits fréquents à la fois rapides et économes en stockage.
• Précisez les motifs dans .gitattributes : lors de la définition des motifs pour Xet ou LFS, utilisez des extensions de fichiers précises (par exemple, *.safetensors, *.bin) afin d'éviter de diriger inutilement les fichiers plus petits vers le stockage de fichiers volumineux.
• Privilégier l’accès de la communauté : Xet augmente considérablement l’efficacité et l’échelle des transferts de fichiers volumineux. Plutôt que de structurer votre dépôt pour réduire sa taille totale (ou la taille des fichiers individuels), organisez-le pour les collaborateurs et les utilisateurs de la communauté afin qu’ils puissent facilement naviguer et récupérer le contenu dont ils ont besoin.

Variables d'environnement

À la fois hf_xet et Git Xet sont propulsés par xet-core, qui peut être configuré via des variables d’environnement. Les tableaux ci-dessous répertorient les variables individuelles pour un contrôle fin. La plupart des utilisateurs n’auront pas besoin de modifier l’une de ces variables — les valeurs par défaut sont calibrées pour saturer automatiquement la plupart des chemins réseau.

HF_XET_HIGH_PERFORMANCE=1 est un drapeau de commodité qui ajuste plusieurs paramètres d’un coup (limites de concurrence, tailles de tampon et limites de fichiers parallèles). Il est destiné aux machines disposant d’une bande passante élevée et d’un disque rapide. À partir de hf_xet 1.7.0, les tailles de tampon qu’il définit sont basées sur la mémoire disponible pour hf_xet (voir Tampons de téléchargement), il n’a donc plus besoin de 64 Go de RAM, et toute variable que vous définissez vous-même prend le pas sur ce drapeau. Avec les versions antérieures, ne l’utilisez que sur des machines dotées d’au moins 64 Go de RAM.

Général

Drapeaux de haut niveau auxquels la plupart des utilisateurs pensent en premier.

Concurrence adaptative

Par défaut, xet-core utilise une concurrence adaptative — il ajuste dynamiquement le parallélisme en fonction des conditions réseau en temps réel. Il s’agit de paramètres avancés qui ne sont généralement pas nécessaires dans la plupart des cas. Les variables ci-dessous contrôlent le comportement du contrôleur adaptatif :

Pour fixer la concurrence à une valeur donnée (en contournant le contrôleur adaptatif), utilisez les alias de commodité HF_XET_FIXED_UPLOAD_CONCURRENCY et HF_XET_FIXED_DOWNLOAD_CONCURRENCY. Ces derniers définissent la concurrence initiale, minimale et maximale à la même valeur.

Réseau et nouvelle tentative

Transfert de données

Télécharger les tampons

Ces paramètres contrôlent l'utilisation de la mémoire pendant les téléchargements.

À partir de hf_xet 1.7.0, les valeurs par défaut des trois variables DOWNLOAD_BUFFER sont basées sur la quantité de mémoire dont hf_xet peut disposer. Il s’agit de la RAM de la machine, ou de la limite de mémoire du conteneur si celle-ci est plus basse. Chaque valeur par défaut est une fraction de cette mémoire, maintenue entre le minimum et le maximum indiqués dans le tableau. Le mode HP utilise le double de cette fraction, avec les mêmes minimum et maximum. Par exemple, un conteneur limité à 4 Go obtient un tampon d’environ 256 Mo avec une limite de 1 Go, et une machine dotée de 32 Go obtient environ le même tampon de 2 Go et la même limite de 8 Go que les versions précédentes.

Les versions antérieures, ou toute version qui ne peut pas déterminer la quantité de mémoire disponible, utilisent des valeurs par défaut fixes de 2gb, 512mb et 8gb (16gb, 2gb et 64gb en mode HP). Les valeurs utilisées sont écrites dans le fichier de journal hf_xet au démarrage (voir Journalisation).

Cache de shards

Le cache de shards conserve sur disque, sous le répertoire de cache Xet, l’index de déduplication (les « shards » décrivant les fragments déjà téléversés). Un cache plus volumineux permet au client de dédupliquer par rapport à davantage de données déjà vues, ce qui réduit le nombre d’octets retéléversés.

Cache de blocs

hf_xet n'utilise plus de cache local de chunks pour les téléchargements. Les fichiers téléchargés sont toujours stockés dans le cache basé sur les fichiers de huggingface_hub.

Journalisation

Télémétrie

hf_xet envoie un court rapport après chaque téléversement et téléchargement. Consultez Télémétrie pour en connaître le contenu. Pour le désactiver, définissez HF_HUB_DISABLE_TELEMETRY=1.

Limites actuelles

Bien que Xet apporte une déduplication fine et des performances améliorées au stockage basé sur Git, certaines fonctionnalités et compatibilités de plateforme sont encore en cours de développement. Par conséquent, gardez les contraintes suivantes à l’esprit lors du travail avec un dépôt activé pour Xet :

• Systèmes 64 bits uniquement : hf_xet et Git Xet nécessitent actuellement tous deux une architecture 64 bits ; les systèmes 32 bits ne sont pas pris en charge.