Migration vers huggingface_hub v1.0

La version v1.0 est une étape majeure pour la bibliothèque huggingface_hub. Elle marque notre engagement envers la stabilité de l'API et la maturité de la bibliothèque. Nous avons apporté plusieurs améliorations et modifications cassantes pour rendre la bibliothèque plus robuste et plus facile à utiliser.

Ce guide est conçu pour vous aider à migrer votre code existant vers la nouvelle version. Si vous avez des questions ou des commentaires, n'hésitez pas à nous le faire savoir en ouvrant un ticket sur GitHub.

Python 3.9+

huggingface_hub nécessite désormais Python 3.9 ou une version supérieure. Python 3.8 n'est plus pris en charge.

Migration vers HTTPX

La bibliothèque huggingface_hub utilise désormais httpx au lieu de requests pour les requêtes HTTP. Ce changement a été effectué pour améliorer les performances et pour prendre en charge les requêtes synchrones et asynchrones de la même manière. Nous avons donc supprimé les dépendances requests et aiohttp.

Changements majeurs

Il s'agit d'une modification majeure qui affecte l'ensemble de la bibliothèque. Bien que nous ayons cherché à rendre ce changement aussi transparent que possible, il se peut que vous deviez mettre à jour votre code dans certains cas. Voici la liste des modifications cassantes introduites dans le processus :

• Configuration du proxy : les proxys « par méthode » ne sont plus pris en charge. Les proxys doivent être configurés de manière globale à l’aide des variables d’environnement HTTP_PROXY et HTTPS_PROXY.
• Backend HTTP personnalisé : la fonction configure_http_backend a été supprimée. Vous devez désormais utiliser set_client_factory() et set_async_client_factory() pour configurer les clients HTTP.
• Gestion des erreurs : les erreurs HTTP ne sont plus héritées de requests.HTTPError, mais de httpx.HTTPError. Nous recommandons d’attraper HfHubHTTPError (importé avec from huggingface_hub.utils import HfHubHTTPError), qui est une sous-classe de requests.HTTPError en v0.x et de httpx.HTTPError en v1.x. Attraper l’erreur depuis huggingface_hub garantit que votre code est compatible avec les anciennes et les nouvelles versions de la bibliothèque.
• SSLError : httpx ne possède pas le concept de SSLError. Il s'agit désormais d'une erreur générique httpx.ConnectError.
• LocalEntryNotFoundError : cette erreur n’hérite plus de HTTPError. Nous définissons désormais EntryNotFoundError (nouvelle), dont héritent à la fois LocalEntryNotFoundError (si le fichier n’est pas trouvé dans le cache local) et RemoteEntryNotFoundError (si le fichier n’est pas trouvé dans le dépôt sur le Hub). Seule l’erreur distante hérite de HTTPError.
• InferenceClient : le InferenceClient peut désormais être utilisé comme gestionnaire de contexte. C'est particulièrement utile lors du streaming de tokens depuis un modèle de langage pour s'assurer que la connexion est correctement fermée.
• AsyncInferenceClient : le paramètre trust_env a été supprimé du constructeur de AsyncInferenceClient. Les variables d’environnement sont faites confiance par défaut par httpx. Si vous ne souhaitez pas explicitement faire confiance à l’environnement, vous devez le configurer avec set_async_client_factory().

Pour plus de détails, vous pouvez consulter PR #3328 qui a introduit httpx.

Pourquoi httpx ?

La migration de requests vers httpx apporte plusieurs améliorations clés qui renforcent les performances, la fiabilité et la maintenabilité de la bibliothèque :

Sécurité des threads et réutilisation des connexions : httpx est conçu pour être sûr en environnement multithreadé, ce qui nous permet de réutiliser en toute sécurité le même client à travers plusieurs threads. Cette réutilisation des connexions réduit le surcoût lié à l'établissement de nouvelles connexions pour chaque requête HTTP, améliorant ainsi les performances, en particulier lors de requêtes fréquentes vers le Hub.

Prise en charge de HTTP/2 : httpx offre une prise en charge native de HTTP/2, ce qui permet une meilleure efficacité lors de l'envoi de plusieurs requêtes vers le même serveur (ce qui correspond exactement à notre cas d'usage). Cela se traduit par une latence plus faible et une consommation de ressources réduite par rapport à HTTP/1.1.

API unifiée synchrone/asynchrone : Contrairement à notre configuration précédente qui utilisait des dépendances distinctes requests (synchrone) et aiohttp (asynchrone), httpx fournit des clients synchrones et asynchrones au comportement identique. Cela garantit que InferenceClient et AsyncInferenceClient disposent de fonctionnalités cohérentes et élimine les différences subtiles de comportement qui existaient auparavant entre les deux implémentations.

Gestion améliorée des erreurs SSL : httpx gère les erreurs SSL de manière plus souple, ce qui facilite et fiabilise le débogage des problèmes de connexion.

Architecture pérenne : httpx est activement maintenu et conçu pour les applications Python modernes. En revanche, requests est en mode maintenance et ne recevra pas de mises à jour majeures telles que des améliorations de la sécurité des threads ou la prise en charge de HTTP/2.

Gestion améliorée des variables d’environnement : httpx offre une gestion plus cohérente des variables d’environnement dans les contextes synchrones et asynchrones, éliminant les incohérences précédentes où requests lisait les variables d’environnement locales par défaut tandis que aiohttp ne le faisait pas.

Le passage à httpx dote huggingface_hub d’un backend HTTP moderne, efficace et maintenable. Bien que la plupart des utilisateurs devraient constater un fonctionnement sans accroc, les améliorations sous-jacentes offrent de meilleures performances et une plus grande fiabilité pour toutes les interactions avec le Hub.

hf_transfer

Maintenant que tous les dépôts du Hub sont activés pour Xet et que hf_xet est la méthode par défaut pour télécharger/téléverser des fichiers, nous avons supprimé la prise en charge du package optionnel hf_transfer. La variable d’environnement HF_HUB_ENABLE_HF_TRANSFER est donc ignorée. Utilisez à la place HF_XET_HIGH_PERFORMANCE.

Classe de dépôt

La classe Repository a été supprimée dans la v1.0. Il s’agissait d’un simple wrapper autour de l’interface en ligne de commande git pour la gestion des dépôts. Vous pouvez toujours utiliser git directement dans le terminal, mais l’approche recommandée est d’utiliser l’API basée sur HTTP de la bibliothèque huggingface_hub pour une expérience plus fluide, en particulier lors de la manipulation de fichiers volumineux.

Voici une correspondance entre la classe Repository de la version précédente et la nouvelle classe HfApi :

méthode Repository	méthode de HfApi
repo.clone_from	snapshot_download
repo.git_add + git_commit + git_push	upload_file(), upload_folder(), create_commit()
repo.git_tag	create_tag
repo.git_branch	create_branch

Classe HfFolder

HfFolder était utilisé pour gérer le jeton d’accès de l’utilisateur. Utilisez login() pour enregistrer un nouveau jeton, logout() pour le supprimer et whoami() pour vérifier l’utilisateur associé au jeton actuel. Enfin, utilisez get_token() pour récupérer le jeton de l’utilisateur dans un script.

Classe InferenceApi

InferenceApi était une classe pour interagir avec l'API d'inférence. Il est désormais recommandé d'utiliser la classe InferenceClient à la place.

Autres fonctionnalités obsolètes

Certaines méthodes et certains paramètres ont été supprimés dans la v1.0. Ceux qui sont listés ci-dessous étaient déjà obsolètes avec un message d'avertissement dans la v0.x.

• constants.hf_cache_home a été supprimé. Veuillez utiliser HF_HOME à la place.
• Les paramètres use_auth_token ont été supprimés de toutes les méthodes. Veuillez utiliser token à la place.
• La méthode get_token_permission a été supprimée.
• La méthode update_repo_visibility a été supprimée. Veuillez utiliser update_repo_settings à la place.
• Le paramètre is_write_action a été supprimé de build_hf_headers, tout comme write_permission de login. Le concept de « permission d’écriture » a été supprimé et n’est plus pertinent maintenant que les jetons à granularité fine sont l’approche recommandée.
• Le paramètre new_session de login a été renommé en skip_if_logged_in pour plus de clarté.
• Les paramètres resume_download, force_filename et local_dir_use_symlinks ont été supprimés de hf_hub_download et snapshot_download.
• Les paramètres library, language, tags et task ont été supprimés de list_models.

Commandes de cache CLI

La gestion du cache depuis l’interface en ligne de commande a été repensée pour suivre un flux de travail inspiré de Docker. L’outil huggingface-cli, désormais obsolète, a été supprimé ; hf (introduit dans la v0.34) le remplace par une interface en ligne de commande ressource-action plus claire. Les commandes héritées hf cache scan et hf cache delete sont également supprimées dans la v1.0 et remplacées par le trio suivant :

• hf cache ls liste les entrées du cache avec une sortie en tableau concis, JSON ou CSV. Utilisez --revisions pour inspecter des révisions individuelles, ajoutez des expressions --filter telles que size>1GB ou accessed>30d, et combinez-les avec --quiet si vous n’avez besoin que des identifiants.
• hf cache rm supprime les entrées de cache sélectionnées. Passez un ou plusieurs identifiants de dépôt (par exemple model/bert-base-uncased) ou des hachages de révision, et ajoutez éventuellement --dry-run pour un aperçu ou --yes pour ignorer la demande de confirmation. Cela remplace à la fois les flux de travail interactifs TUI et --disable-tui de la commande précédente.
• hf cache prune exécute la tâche de nettoyage courante consistant à supprimer les révisions non référencées en une seule fois. Ajoutez --dry-run ou --yes de la même manière qu’avec hf cache rm.

Enfin, l'extra [cli] a été supprimé - le CLI est désormais fourni avec le package principal huggingface_hub.

Prise en charge de TensorFlow et Keras 2.x

Tout le code et les dépendances liés à TensorFlow ont été supprimés dans la v1.0. Cela inclut les modifications cassantes suivantes :

• huggingface_hub[tensorflow] n'est plus une dépendance supplémentaire prise en charge
• Les fonctions utilitaires split_tf_state_dict_into_shards et get_tf_storage_size ont été supprimées.
• Les versions tensorflow, fastai et fastcore ne sont plus incluses dans les en-têtes intégrés.

L'intégration Keras 2.x a également été supprimée. Cela inclut la classe KerasModelHubMixin ainsi que les utilitaires save_pretrained_keras, from_pretrained_keras et push_to_hub_keras. Keras 2.x est une bibliothèque obsolète et non maintenue. L'approche recommandée est d'utiliser Keras 3.x, qui est étroitement intégré au Hub (c'est-à-dire qu'il contient des méthodes intégrées pour charger/pousser vers le Hub). Si vous souhaitez toujours travailler avec Keras 2.x, vous devez rétrograder huggingface_hub à une version v0.x.

valeurs de retour de upload_file et upload_folder

Les fonctions upload_file() et upload_folder() renvoient désormais l’URL de l’engagement créé sur le Hub. Auparavant, elles renvoyaient l’URL du fichier ou du dossier. Cela permet d’aligner la valeur de retour sur celle de create_commit(), delete_file() et delete_folder().

Update on GitHub