# 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](https://github.com/huggingface/huggingface_hub/issues). ## 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`](https://www.python-httpx.org/) 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()](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.set_client_factory) et [set_async_client_factory()](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.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](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.errors.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()](/docs/huggingface_hub/main/fr/package_reference/utilities#huggingface_hub.set_async_client_factory). Pour plus de détails, vous pouvez consulter [PR #3328](https://github.com/huggingface/huggingface_hub/pull/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`](../package_reference/environment_variables). ## classe `Repository` 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()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.upload_file), [upload_folder()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.upload_folder), [create_commit()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/main/fr/package_reference/authentication#huggingface_hub.login) pour enregistrer un nouveau jeton, [logout()](/docs/huggingface_hub/main/fr/package_reference/authentication#huggingface_hub.logout) pour le supprimer et [whoami()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.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](/docs/huggingface_hub/main/fr/package_reference/inference_client#huggingface_hub.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. ## Les valeurs renvoyées par `upload_file` et `upload_folder` Les fonctions [upload_file()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.upload_file) et [upload_folder()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.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()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.create_commit), [delete_file()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.delete_file) et [delete_folder()](/docs/huggingface_hub/main/fr/package_reference/hf_api#huggingface_hub.HfApi.delete_folder).