# Démarrage rapide Le [Hugging Face Hub](https://huggingface.co/) est la référence pour partager des modèles de machine learning, des démos, des jeux de données et des métriques. La bibliothèque `huggingface_hub` vous aide à interagir avec le Hub sans quitter votre environnement de développement. Vous pouvez créer et gérer des dépôts facilement, télécharger et téléverser des fichiers, et obtenir des métadonnées utiles sur les modèles et les jeux de données depuis le Hub. ## Installation Pour commencer, installez la bibliothèque `huggingface_hub` : ```bash pip install --upgrade huggingface_hub ``` Pour plus de détails, consultez le guide d'[installation](installation). > [!TIP] > Le `huggingface_hub` est également livré avec une [CLI `hf`](./guides/cli) qui vous permet d'interagir avec le Hub directement depuis le terminal. Si vous utilisez des agents IA (Claude Code, Codex, Cursor, ...), installez le Skill pour permettre à votre agent d'utiliser la CLI : > ```bash > # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` > hf skills add > ``` > Consultez le guide [Hugging Face CLI for AI Agents](https://huggingface.co/docs/hub/agents-cli) pour plus de détails. ## Télécharger les fichiers Les dépôts sur le Hub sont gérés par le contrôle de version git, et les utilisateurs peuvent télécharger un fichier unique ou l'intégralité du dépôt. Vous pouvez utiliser la fonction [hf_hub_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.hf_hub_download) pour télécharger des fichiers. Cette fonction télécharge et met en cache un fichier sur votre disque local. La prochaine fois que vous aurez besoin de ce fichier, il sera chargé depuis votre cache, vous n'aurez donc pas besoin de le retélécharger. Vous aurez besoin de l'identifiant du dépôt et du nom du fichier que vous souhaitez télécharger. Par exemple, pour télécharger le fichier de configuration du modèle [Pegasus](https://huggingface.co/google/pegasus-xsum) : ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") ``` Pour télécharger une version spécifique du fichier, utilisez le paramètre `revision` pour indiquer le nom de la branche, le tag ou l’empreinte de commit. Si vous choisissez d’utiliser l’empreinte de commit, elle doit être l’empreinte complète et non l’empreinte courte de 7 caractères : ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download( ... repo_id="google/pegasus-xsum", ... filename="config.json", ... revision="4d33b01d79672f27f001f6abade33f22d993b151" ... ) ``` Pour plus de détails et d'options, consultez la référence de l'API de [hf_hub_download()](/docs/huggingface_hub/v2.4.0/fr/package_reference/file_download#huggingface_hub.hf_hub_download). ## Authentification Dans de nombreux cas, vous devez être authentifié avec un compte Hugging Face pour interagir avec le Hub : télécharger des dépôts privés, téléverser des fichiers, créer des PR, etc. [Créez un compte](https://huggingface.co/join) si vous n'en avez pas encore. ### Commande de connexion La façon la plus simple de s’authentifier est d’utiliser la commande [login()](/docs/huggingface_hub/v2.4.0/fr/package_reference/authentication#huggingface_hub.login) : ```bash hf auth login ``` Si vous êtes déjà connecté, la commande se termine immédiatement. Pour forcer une nouvelle connexion, utilisez `hf auth login --force`. Si vous n’êtes pas connecté, on vous demandera de vous connecter via votre navigateur : ouvrez l’URL affichée, saisissez le code court, approuvez la demande, puis un jeton d’accès est récupéré et enregistré dans votre répertoire `HF_HOME` (par défaut `~/.cache/huggingface/token`). Le jeton expire après un certain temps, mais il est renouvelé automatiquement tant que vous continuez à l’utiliser. Tout script ou bibliothèque interagissant avec le Hub utilisera ce jeton lors de l’envoi de requêtes. Vous pouvez également coller un [User Access Token](https://huggingface.co/docs/hub/security-tokens) généré depuis votre [Settings page](https://huggingface.co/settings/tokens). > [!TIP] > Les jetons d’accès utilisateur peuvent disposer des autorisations `read` ou `write`. Assurez-vous de disposer d’un jeton d’accès `write` si vous souhaitez créer ou modifier un dépôt. Sinon, il est préférable de générer un jeton `read` afin de réduire les risques en cas de fuite accidentelle de votre jeton. Sinon, vous pouvez vous connecter de manière programmatique en utilisant [login()](/docs/huggingface_hub/v2.4.0/fr/package_reference/authentication#huggingface_hub.login) dans un notebook ou un script : ```py >>> from huggingface_hub import login >>> login() ``` Vous ne pouvez être connecté qu’à un seul compte à la fois. La connexion à un nouveau compte vous déconnecte automatiquement du précédent. Pour déterminer le compte actuellement actif, exécutez simplement la commande `hf auth whoami`. > [!WARNING] > Une fois connecté, toutes les requêtes vers le Hub – y compris les méthodes qui n'exigent pas nécessairement d'authentification – utiliseront par défaut votre jeton d'accès. Si vous souhaitez désactiver l'utilisation implicite de votre jeton, vous devez définir `HF_HUB_DISABLE_IMPLICIT_TOKEN=1` en tant que variable d'environnement (voir [référence](../package_reference/environment_variables#hfhubdisableimplicittoken)). ### Gérer plusieurs jetons localement Vous pouvez enregistrer plusieurs jetons sur votre machine en vous connectant simplement avec la commande [login()](/docs/huggingface_hub/v2.4.0/fr/package_reference/authentication#huggingface_hub.login) pour chaque jeton. Si vous devez basculer entre ces jetons localement, vous pouvez utiliser la commande `auth switch` : ```bash hf auth switch ``` Cette commande vous invite à sélectionner un jeton par son nom à partir d'une liste de jetons enregistrés. Une fois sélectionné, le jeton choisi devient le jeton _actif_ et sera utilisé pour toutes les interactions avec le Hub. Vous pouvez lister tous les jetons d'accès disponibles sur votre machine avec `hf auth list`. ### Variable d'environnement La variable d’environnement `HF_TOKEN` peut également être utilisée pour vous authentifier. C’est particulièrement utile dans un Space où vous pouvez définir `HF_TOKEN` comme [secret de Space](https://huggingface.co/docs/hub/spaces-overview#managing-secrets). > [!TIP] > **NOUVEAU :** Google Colaboratory vous permet de définir des [clés privées](https://twitter.com/GoogleColab/status/1719798406195867814) pour vos notebooks. Définissez un secret `HF_TOKEN` pour être authentifié automatiquement ! L'authentification via une variable d'environnement ou un secret a la priorité sur le jeton stocké sur votre machine. ### Paramètres de la méthode Enfin, il est également possible de s'authentifier en passant votre jeton à toute méthode qui accepte `token` en tant que paramètre. ``` from huggingface_hub import whoami user = whoami(token=...) ``` Cela est généralement déconseillé, sauf dans un environnement où vous ne souhaitez pas stocker votre jeton de manière permanente ou si vous devez gérer plusieurs jetons simultanément. > [!WARNING] > Veuillez faire preuve de prudence lors de la transmission de jetons en tant que paramètre. La meilleure pratique consiste toujours à charger le jeton depuis un coffre-fort sécurisé plutôt que de le coder en dur dans votre base de code ou votre notebook. Les jetons codés en dur présentent un risque majeur de fuite si vous partagez votre code par inadvertance. ## Créer un dépôt Une fois votre inscription et votre connexion effectuées, créez un dépôt à l'aide de la fonction [create_repo()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_api#huggingface_hub.HfApi.create_repo) : ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model") ``` Si vous souhaitez que votre dépôt soit privé, alors : ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model", private=True) ``` Les dépôts privés ne seront visibles que par vous-même. > [!TIP] > Pour créer un dépôt ou pousser du contenu vers le Hub, vous devez fournir un jeton d'accès utilisateur disposant de l'autorisation `write`. Vous pouvez choisir l'autorisation lors de la création du jeton sur votre [page Paramètres](https://huggingface.co/settings/tokens). ## Téléverser des fichiers Utilisez la fonction [upload_file()](/docs/huggingface_hub/v2.4.0/fr/package_reference/hf_api#huggingface_hub.HfApi.upload_file) pour ajouter un fichier à votre nouvellement créé dépôt. Vous devez spécifier : 1. Le chemin du fichier à téléverser. 2. Le chemin du fichier dans le dépôt. 3. L'identifiant du dépôt où vous souhaitez ajouter le fichier. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/home/lysandre/dummy-test/README.md", ... path_in_repo="README.md", ... repo_id="lysandre/test-model", ... ) ``` Pour téléverser plus d'un fichier à la fois, consultez le guide [Upload](./guides/upload) qui vous présente plusieurs méthodes de téléversement de fichiers (avec ou sans git). ## Étapes suivantes La bibliothèque `huggingface_hub` offre aux utilisateurs un moyen simple d’interagir avec le Hub en Python. Pour en savoir plus sur la gestion de vos fichiers et dépôts sur le Hub, nous vous recommandons de consulter nos [guides pratiques](./guides/overview) pour : - [Gérer votre dépôt](./guides/repository). - [Télécharger](./guides/download) des fichiers depuis le Hub. - [Téléverser](./guides/upload) des fichiers sur le Hub. - [Recherchez sur le Hub](./guides/search) le modèle ou le jeu de données souhaité. - [Exécuter l’inférence](./guides/inference) sur plusieurs services pour les modèles hébergés sur le Hugging Face Hub.