Maîtriser Hugging Face CLI : Connexion sans effort & au-delà

CLI de connexion Hugging Face : Votre passerelle vers les modèles AI

Par Jake Morrison, passionné d’automatisation AI

Le monde de l’IA évolue rapidement, et l’accès à des modèles puissants est essentiel pour rester à la pointe. Hugging Face est devenu un hub central pour l’apprentissage automatique, offrant un vaste répertoire de modèles pré-entraînés, de jeux de données et d’outils. Bien que leur interface web soit excellente, pour de nombreux développeurs IA et passionnés d’automatisation, interagir avec Hugging Face directement depuis l’interface de ligne de commande (CLI) est essentiel. Cet article vous guidera à travers les étapes pratiques d’utilisation du CLI de connexion Hugging Face, rendant vos flux de travail IA plus fluides et plus efficaces.

Pourquoi utiliser le CLI de connexion Hugging Face ?

Pour l’automatisation, les scripts et les opérations côté serveur, le CLI est roi. Lorsque vous déployez des modèles en production, exécutez des tâches d’entraînement sur des serveurs distants, ou intégrez des modèles Hugging Face dans des pipelines complexes, compter sur un navigateur web n’est pas pratique. Le CLI de connexion Hugging Face fournit un moyen sécurisé et programmatique d’authentifier vos scripts et applications, leur donnant accès à des modèles privés, à des jeux de données et à des fonctionnalités de l’API.

Pensez à ces scénarios :

* **Déploiement de modèles automatisé :** Votre pipeline CI/CD doit déployer un modèle finement ajusté dans votre dépôt Hugging Face privé.
* **Inférence par lots :** Vous exécutez un script qui traite des milliers d’entrées en utilisant un modèle Hugging Face spécifique, et ce modèle nécessite une authentification.
* **Entraînement sur des instances cloud :** Votre script d’entraînement sur une instance AWS EC2 doit télécharger un jeu de données privé depuis Hugging Face avant de commencer.
* **Téléchargements de modèles scriptés :** Vous souhaitez écrire un script pour tirer automatiquement la dernière version d’un modèle pour le développement local.

Dans tous ces cas, le CLI de connexion Hugging Face est l’outil dont vous avez besoin.

Prérequis : Ce dont vous avez besoin avant de commencer

Avant d’explorer les commandes, assurez-vous d’avoir les éléments suivants configurés :

* **Python installé :** Les bibliothèques Hugging Face sont basées sur Python. Vous aurez besoin de Python 3.7 ou plus récent.
* **Gestionnaire de packages `pip` :** Cela vient généralement avec Python.
* **Compte Hugging Face :** Vous avez besoin d’un compte sur huggingface.co. Si vous n’en avez pas, inscrivez-vous gratuitement.
* **Connexion Internet :** Pour vous connecter à Hugging Face.

Étape 1 : Installer la bibliothèque `huggingface_hub`

Le cœur de l’interaction avec Hugging Face depuis Python et le CLI est la bibliothèque `huggingface_hub`. Si vous ne l’avez pas installée, ouvrez votre terminal ou invite de commandes et exécutez :

“`bash
pip install huggingface_hub
“`

Cette commande télécharge et installe les composants nécessaires. Il est conseillé de le faire dans un environnement virtuel pour garder vos dépendances de projet isolées.

“`bash
# Exemple utilisant un environnement virtuel
python -m venv .venv
source .venv/bin/activate # Sur Windows : .venv\Scripts\activate
pip install huggingface_hub
“`

Une fois installé, vous êtes prêt à utiliser le CLI de connexion Hugging Face.

Étape 2 : Générez votre jeton d’accès Hugging Face

Le CLI de connexion Hugging Face n’utilise pas directement votre nom d’utilisateur et votre mot de passe habituels pour l’authentification. Au lieu de cela, il repose sur des jetons API (également appelés jetons d’accès ou jetons d’authentification). Ces jetons sont sécurisés, révocables, et vous permettent de donner des permissions spécifiques.

1. **Connectez-vous à Hugging Face :** Allez sur huggingface.co et connectez-vous avec votre compte.
2. **Accédez aux paramètres :** Cliquez sur votre photo de profil dans le coin supérieur droit, puis sélectionnez “Paramètres.”
3. **Allez aux jetons d’accès :** Dans le menu de gauche, cliquez sur “Jetons d’accès.”
4. **Créez un nouveau jeton :** Cliquez sur le bouton “Nouveau jeton”.
5. **Configurez votre jeton :**
* **Nom :** Donnez à votre jeton un nom descriptif (par exemple, “Jeton d’automatisation CLI,” “Mon jeton serveur”). Cela vous aidera à vous souvenir de son utilité.
* **Rôle :** Ceci est crucial.
* **`read` :** Permet de télécharger des modèles et des jeux de données publics, et de lire des informations. Cela est souvent suffisant pour des scripts d’inférence.
* **`write` :** Permet de pousser des modèles, des jeux de données et des espaces, en plus des permissions `read`. Choisissez cela si vos scripts doivent télécharger du contenu.
* **`admin` :** Contrôle total. À utiliser avec précaution.
* Pour la plupart des tâches d’automatisation, `read` ou `write` suffiront. Commencez avec le rôle le moins permissif requis.
6. **Générez et copiez :** Cliquez sur “Générer un jeton.” Hugging Face affichera votre nouveau jeton. **Copiez immédiatement ce jeton !** Pour des raisons de sécurité, il ne sera affiché qu’une seule fois. Si vous le perdez, vous devrez en générer un nouveau.

Gardez ce jeton en sécurité. Traitez-le comme un mot de passe. Ne le codez pas en dur directement dans des dépôts publics ou ne le partagez pas inutilement.

Étape 3 : Utiliser le CLI de connexion Hugging Face

Maintenant que vous avez votre jeton, vous pouvez utiliser le CLI de connexion Hugging Face pour authentifier votre environnement. Ouvrez votre terminal ou invite de commandes.

La commande principale pour l’authentification est `huggingface-cli login`.

“`bash
huggingface-cli login
“`

Lorsque vous exécutez cette commande, le CLI vous demandera de coller votre jeton :

“`
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _|
_|_| _|_| _| _| _| _| _| _| _| _|_| _|
_|_|_|_| _|_|_| _| _| _| _| _| _| _| _| _|_|
_| _| _| _| _| _| _| _| _| _| _|
_| _| _|_| _|_| _|_|_| _|_|_| _|_|_| _| _|

Pour plus d’informations sur la façon d’obtenir un jeton, veuillez aller sur https://huggingface.co/docs/hub/security-tokens
Jeton :
“`

Collez votre jeton d’accès copié ici et appuyez sur Entrée.

Si cela réussit, vous verrez un message comme :

“`
Le jeton a été enregistré dans /home/youruser/.cache/huggingface/token
Connexion réussie
“`

Ce message confirme que votre jeton a été enregistré dans un fichier cache local. Le CLI de connexion Hugging Face stocke ce jeton en toute sécurité dans le répertoire personnel de votre utilisateur (par exemple, `~/.cache/huggingface/token` sur Linux/macOS, ou `C:\Users\YourUser\.cache\huggingface\token` sur Windows). Les opérations suivantes utilisant `huggingface_hub` dans votre environnement utiliseront automatiquement ce jeton stocké pour l’authentification.

Vérifier votre connexion

Vous pouvez vérifier que vous êtes connecté en essayant d’accéder à une ressource restreinte ou simplement en exécutant :

“`bash
huggingface-cli whoami
“`

Cette commande affichera des informations sur l’utilisateur associé au jeton actuellement connecté, confirmant votre statut d’authentification.

Méthodes d’authentification alternatives (au-delà de `huggingface-cli login`)

Alors que `huggingface-cli login` est la méthode la plus courante pour s’authentifier lors de sessions interactives et de développement, il existe d’autres méthodes utiles pour des scénarios spécifiques.

1. Utilisation de variables d’environnement

Pour des environnements non-interactifs comme les pipelines CI/CD, les conteneurs Docker ou les fonctions cloud, passer le jeton via une variable d’environnement est souvent préférable. Cela évite d’écrire le jeton dans un fichier sur l’environnement éphémère.

Définissez la variable d’environnement `HF_TOKEN` avant d’exécuter votre script Python ou votre commande :

“`bash
export HF_TOKEN=”hf_YOUR_ACTUAL_TOKEN_HERE”
# Maintenant exécutez votre script ou toute commande huggingface_hub
python my_model_script.py
“`

Sur Windows :

“`cmd
set HF_TOKEN=”hf_YOUR_ACTUAL_TOKEN_HERE”
python my_model_script.py
“`

La bibliothèque `huggingface_hub` et les commandes CLI de connexion Hugging Face vérifient automatiquement la variable d’environnement `HF_TOKEN` si aucun jeton n’est trouvé dans le cache local.

2. Passer le jeton directement dans Python

Si vous avez besoin d’un contrôle très précis ou si vous opérez dans un environnement où la définition de variables d’environnement ou l’utilisation de la connexion CLI n’est pas réalisable, vous pouvez passer le jeton directement aux fonctions `huggingface_hub` dans votre code Python.

“`python
from huggingface_hub import HfApi

# AVERTISSEMENT : Évitez de coder les jetons en dur directement dans le code de production.
# Utilisez plutôt des variables d’environnement ou un système de gestion de configuration sécurisé.
token = “hf_YOUR_ACTUAL_TOKEN_HERE”

api = HfApi(token=token)

# Exemple : Lister vos modèles privés
private_models = api.list_models(author=”your_username”, private=True)
for model in private_models:
print(model.modelId)

# Exemple : Télécharger un modèle privé
from transformers import AutoModelForSequenceClassification, AutoTokenizer

model_name = “your_username/your_private_model”
tokenizer = AutoTokenizer.from_pretrained(model_name, token=token)
model = AutoModelForSequenceClassification.from_pretrained(model_name, token=token)
“`

Remarquez l’argument `token=token` dans le constructeur `HfApi` et les appels `from_pretrained`. Cela indique explicitement aux fonctions quel jeton utiliser pour cette opération spécifique.

Cas d’utilisation courants après le CLI de connexion Hugging Face

Une fois que vous vous êtes authentifié avec le CLI de connexion Hugging Face, vous déverrouillez une gamme de capacités puissantes.

Téléchargement de modèles et de jeux de données privés

Si vous avez des modèles ou des jeux de données privés sur Hugging Face, ou si vous devez accéder à des modèles restreints qui nécessitent une acceptation des conditions d’utilisation, l’authentification est obligatoire.

“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer

# Supposons que vous ayez déjà exécuté ‘huggingface-cli login’ ou défini HF_TOKEN
model_name = “your_org/your_private_model” # Ou un modèle restreint comme meta-llama/Llama-2-7b-hf
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)

print(f”Chargement réussi de {model_name}”)
“`

La fonction `from_pretrained` récupérera automatiquement le token enregistré par le CLI de connexion de Hugging Face.

Téléchargement de modèles et d’ensembles de données

Si votre flux de travail implique de peaufiner des modèles puis de les renvoyer sur Hugging Face, vous aurez besoin d’un token avec des autorisations de `write`.

“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
from datasets import Dataset

# Supposons que vous ayez peaufiné un modèle et que vous ayez un tokenizer
# model = your_fine_tuned_model
# tokenizer = your_tokenizer

# Définissez l’ID de votre dépôt (par exemple, “your_username/your_new_model”)
repo_id = “your_username/my-finetuned-model”

# Poussez le modèle et le tokenizer
model.push_to_hub(repo_id)
tokenizer.push_to_hub(repo_id)

print(f”Modèle et tokenizer poussés vers {repo_id}”)

# Exemple pour les ensembles de données
# my_dataset = Dataset.from_dict({“text”: [“hello”, “world”]})
# my_dataset.push_to_hub(“your_username/my-new-dataset”)
“`

Les méthodes `push_to_hub` utiliseront également le token fourni par le CLI de connexion de Hugging Face.

Gestion de vos tokens

Périodiquement, vous pourriez avoir besoin de gérer vos tokens d’accès.

* **Révocation de tokens :** Si un token est compromis ou n’est plus nécessaire, allez dans les paramètres de votre Hugging Face “Access Tokens” et supprimez-le. Cela invalide immédiatement le token.
* **Liste des tokens :** Depuis le CLI, vous ne pouvez pas directement lister *tous* vos tokens de votre compte, mais vous pouvez voir quel token est actuellement actif dans votre environnement en utilisant `huggingface-cli whoami`.

Résolution des problèmes courants

Parfois, les choses ne se passent pas comme prévu. Voici quelques problèmes courants et leurs solutions lorsque vous utilisez le CLI de connexion de Hugging Face.

* **”Token invalide” ou “Erreur d’authentification” :**
* **Fautes de frappe :** Vérifiez que vous avez copié et collé le token correctement. Il n’y a pas d’espaces ni de caractères supplémentaires.
* **Token expiré :** Bien que les tokens Hugging Face n’expirent généralement pas par défaut, assurez-vous qu’il n’a pas été révoqué manuellement.
* **Rôle incorrect :** Le rôle du token (`read`, `write`) est-il suffisant pour l’opération que vous essayez d’effectuer ? Par exemple, un token `read` ne peut pas pousser des modèles.
* **”Commande non trouvée : huggingface-cli” :**
* **Installation :** Assurez-vous que `huggingface_hub` est installé (`pip install huggingface_hub`).
* **PATH :** Assurez-vous que le répertoire de vos scripts Python est dans le PATH de votre système. Si vous êtes dans un environnement virtuel, activez-le.
* **”Connexion réussie” mais toujours des erreurs :**
* **Environnements différents :** Exécutez-vous votre script dans le *même* environnement où vous avez exécuté `huggingface-cli login` ? Si vous changez d’environnements virtuels ou de sessions SSH, le token pourrait ne pas être récupéré automatiquement.
* **Précédence des variables d’environnement :** Si vous définissez également `HF_TOKEN` comme variable d’environnement, cela pourrait prendre le pas sur le token mis en cache.
* **Corruption du cache :** Dans de rares cas, le fichier de cache du token peut être corrompu. Vous pouvez essayer de supprimer le fichier (`~/.cache/huggingface/token`) et de relancer `huggingface-cli login`.
* **Problèmes de proxy :** Si vous êtes derrière un proxy d’entreprise, vous devrez peut-être configurer les paramètres de proxy pour `pip` et potentiellement pour `huggingface_hub` s’il a des problèmes de connexion. Cela se fait généralement via des variables d’environnement comme `HTTP_PROXY` et `HTTPS_PROXY`.

Meilleures pratiques de sécurité pour le CLI de connexion de Hugging Face

* **Principe du moindre privilège :** Créez toujours des tokens avec les autorisations minimales nécessaires (`read` vs. `write`).
* **Nom des tokens :** Donnez des noms descriptifs à vos tokens afin de savoir à quoi ils servent.
* **Rotation des tokens :** Pour des applications critiques, envisagez de faire une rotation de vos tokens périodiquement.
* **Variables d’environnement pour la production :** Ne jamais coder en dur les tokens dans votre code, surtout en production. Utilisez des variables d’environnement (`HF_TOKEN`) ou un système de gestion des secrets.
* **Stockage sécurisé :** Le CLI de connexion de Hugging Face stocke le token dans le répertoire de cache de votre utilisateur. Assurez-vous que ce répertoire est protégé par des autorisations standard du système de fichiers.
* **Évitez le mode root :** Ne pas exécuter `huggingface-cli login` en tant qu’utilisateur root sauf si c’est absolument nécessaire, et comprenez les implications en matière de sécurité.

Conclusion

Le CLI de connexion de Hugging Face est un outil fondamental pour quiconque cherchant à intégrer des modèles et des ensembles de données Hugging Face dans ses flux de travail automatisés. En comprenant comment générer des tokens API, utiliser la commande `huggingface-cli login`, et utiliser des méthodes d’authentification alternatives comme les variables d’environnement, vous pouvez rationaliser vos processus de développement et de déploiement d’IA. Adoptez le CLI pour son efficacité et sa puissance, et libérez tout le potentiel de Hugging Face dans vos projets.

—

FAQ

Q1 : À quoi sert la commande `huggingface-cli login` ?

La commande `huggingface-cli login` est utilisée pour authentifier votre environnement local avec Hugging Face Hub. Elle vous demande un token d’accès (que vous générez sur le site Hugging Face) et enregistre ensuite ce token de manière sécurisée dans un fichier de cache local. Cela permet à vos scripts Python et à d’autres opérations de `huggingface_hub` d’accéder à des modèles privés, des ensembles de données, ou d’effectuer des actions comme pousser des modèles sans avoir à saisir à nouveau votre token à chaque fois.

Q2 : Où puis-je obtenir le token nécessaire pour `huggingface-cli login` ?

Vous générez le token à partir des paramètres de votre compte Hugging Face. Connectez-vous à huggingface.co, allez dans vos “Paramètres,” puis naviguez vers “Access Tokens.” Cliquez sur “Nouveau token,” donnez-lui un nom, sélectionnez le rôle approprié (par exemple, `read` ou `write`), et générez-le. N’oubliez pas de copier le token immédiatement car il n’est affiché qu’une seule fois.

Q3 : Que faire si je ne veux pas utiliser `huggingface-cli login` ? Puis-je encore m’authentifier ?

Oui, vous avez quelques alternatives. Pour des environnements non interactifs comme les pipelines CI/CD ou les conteneurs Docker, vous pouvez définir la variable d’environnement `HF_TOKEN` avec votre token d’accès. La bibliothèque `huggingface_hub` le récupérera automatiquement. Alternativement, vous pouvez passer l’argument `token` directement aux fonctions `huggingface_hub` (par exemple, `HfApi(token=”your_token”)` ou `AutoTokenizer.from_pretrained(…, token=”your_token”)`) dans votre code Python, bien que cela soit généralement moins recommandé pour des raisons de sécurité en production.

Q4 : Ma commande `huggingface-cli login` a fonctionné, mais mon script ne peut toujours pas accéder à un modèle privé. Que se passe-t-il ?

Il y a plusieurs possibilités. Tout d’abord, assurez-vous que le token que vous avez utilisé a les autorisations correctes (par exemple, un rôle `read` pour le téléchargement). Deuxièmement, vérifiez que votre script s’exécute dans le *même* environnement (par exemple, le même environnement virtuel ou session utilisateur) où vous avez exécuté `huggingface-cli login`. Si vous définissez également la variable d’environnement `HF_TOKEN`, cela pourrait écraser le token mis en cache, alors vérifiez sa valeur. Enfin, vérifiez l’ID du dépôt du modèle pour vous assurer qu’il est correct et que votre compte y a accès.

🕒 Published: March 26, 2026