Hugging Face Login CLI : Votre passerelle vers les modèles d’IA
Par Jake Morrison, passionné d’automatisation IA
Le monde de l’IA évolue rapidement, et avoir accès à des modèles puissants est essentiel pour rester en tête. Hugging Face s’est imposé comme un centre névralgique pour l’apprentissage automatique, offrant un vaste référentiel 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 en ligne de commande (CLI) est indispensable. Cet article vous guidera à travers les étapes pratiques de l’utilisation de l’outil de connexion Hugging Face CLI, rendant vos flux de travail IA plus fluides et efficaces.
Pourquoi utiliser le Hugging Face Login CLI ?
Pour l’automatisation, le scripting et les opérations côté serveur, la CLI est reine. Quand vous déployez des modèles en production, que vous exécutez des tâches d’entraînement sur des serveurs distants ou que vous intégrez des modèles Hugging Face dans des pipelines complexes, compter sur un navigateur web n’est pas pratique. Le Hugging Face login CLI offre 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 API.
Pensez à ces scénarios :
* **Déploiement de modèle automatisé :** Votre pipeline CI/CD doit pousser un modèle ajusté dans votre référentiel privé Hugging Face.
* **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 extraire automatiquement la dernière version d’un modèle pour le développement local.
Dans tous ces cas, le Hugging Face login CLI est l’outil dont vous avez besoin.
Prérequis : Ce qu’il vous faut avant de commencer
Avant d’explorer les commandes, assurez-vous d’avoir ce qui suit configuré :
* **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 Hugging Face `huggingface_hub`
Le cœur de l’interaction avec Hugging Face depuis Python et la CLI est la bibliothèque `huggingface_hub`. Si vous ne l’avez pas installée, ouvrez votre terminal ou votre invite de commandes et exécutez :
“`bash
pip install huggingface_hub
“`
Cette commande télécharge et installe les composants nécessaires. Il est judicieux de faire cela 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ée, vous êtes prêt à utiliser le Hugging Face login CLI.
Étape 2 : Générer votre jeton d’accès Hugging Face
Le Hugging Face login CLI n’utilise pas directement votre nom d’utilisateur et votre mot de passe habituels pour l’authentification. Au lieu de cela, il s’appuie 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 d’accorder des autorisations spécifiques.
1. **Connectez-vous à Hugging Face :** Rendez-vous 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 dans les 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 de serveur”). Cela vous aidera à en rappeler l’objectif.
* **Rôle :** C’est crucial.
* **`read` :** Permet de télécharger des modèles et jeux de données publics, et de lire des informations. Cela suffit souvent pour les scripts d’inférence.
* **`write` :** Permet de pousser des modèles, jeux de données et espaces, en plus des autorisations `read`. Choisissez ceci si vos scripts doivent télécharger du contenu.
* **`admin` :** Contrôle total. À utiliser avec prudence.
* Pour la plupart des tâches d’automatisation, `read` ou `write` suffira. 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 ce jeton immédiatement !** 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 directement dans des référentiels publics ou ne le partagez pas inutilement.
Étape 3 : Utiliser le Hugging Face Login CLI
Maintenant que vous avez votre jeton, vous pouvez utiliser le Hugging Face login CLI pour authentifier votre environnement. Ouvrez votre terminal ou votre invite de commandes.
La commande principale pour l’authentification est `huggingface-cli login`.
“`bash
huggingface-cli login
“`
Lorsque vous exécutez cette commande, la CLI vous demandera de coller votre jeton :
“`
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _|
_|_| _|_| _| _| _| _| _| _| _| _|_| _|
_|_|_|_| _|_|_| _| _| _| _| _| _| _| _| _|_|
_| _| _| _| _| _| _| _| _| _| _|
_| _| _|_| _|_| _|_|_| _|_|_| _|_|_| _| _|
Pour plus d’informations sur la façon d’obtenir un jeton, veuillez consulter 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 Hugging Face login CLI 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 enregistré pour l’authentification.
Vérification de 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`)
Bien que `huggingface-cli login` soit le moyen le plus courant de s’authentifier pour des sessions interactives et le développement, il existe d’autres méthodes utiles pour des scénarios spécifiques.
1. Utilisation des variables d’environnement
Pour les 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éré. 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 n’importe quelle 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 Hugging Face login CLI vérifient automatiquement la variable d’environnement `HF_TOKEN` si aucun jeton n’est trouvé dans le cache local.
2. Passer le jeton directement en Python
Si vous avez besoin d’un contrôle très précis ou si vous opérez dans un environnement où définir des variables d’environnement ou utiliser la connexion CLI n’est pas pratique, vous pouvez passer le jeton directement aux fonctions `huggingface_hub` dans votre code Python.
“`python
from huggingface_hub import HfApi
# AVERTISSEMENT : Évitez de coder des jetons directement dans le code de production.
# Utilisez des variables d’environnement ou un système de gestion de configuration sécurisé à la place.
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)
“`
Notez 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 Hugging Face Login CLI
Une fois que vous êtes authentifié avec le Hugging Face login CLI, vous débloquez une gamme de capacités puissantes.
Téléchargement de modèles et jeux de données privés
Si vous avez des modèles ou jeux de données privés sur Hugging Face, ou si vous devez accéder à des modèles restreints nécessitant l’acceptation des conditions, 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 jeton enregistré par la commande de connexion Hugging Face.
Chargement de Modèles et Datasets
Si votre flux de travail implique l’ajustement de modèles, puis leur envoi à Hugging Face, vous aurez besoin d’un jeton avec des autorisations `write`.
“`python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
from datasets import Dataset
# Supposons que vous ayez ajusté un modèle et que vous ayez un tokenizer
# model = your_fine_tuned_model
# tokenizer = your_tokenizer
# Définissez votre ID de dépôt (par exemple, “your_username/your_new_model”)
repo_id = “your_username/my-finetuned-model”
# Envoyez le modèle et le tokenizer
model.push_to_hub(repo_id)
tokenizer.push_to_hub(repo_id)
print(f”Modèle et tokenizer envoyés à {repo_id}”)
# Exemple pour les datasets
# 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 jeton fourni par la commande de connexion Hugging Face.
Gestion de Vos Jetons
Périodiquement, vous pourriez avoir besoin de gérer vos jetons d’accès.
* **Révocation de Jetons :** Si un jeton est compromis ou n’est plus nécessaire, allez dans les paramètres “Jetons d’Accès” de Hugging Face et supprimez-le. Cela invalide immédiatement le jeton.
* **Lister les Jetons :** Depuis la CLI, vous ne pouvez pas lister directement *tous* vos jetons de votre compte, mais vous pouvez voir quel jeton est actuellement actif dans votre environnement en utilisant `huggingface-cli whoami`.
Dépannage des Problèmes Courants
Parfois, les choses ne se passent pas comme prévu. Voici quelques problèmes courants et leurs solutions lors de l’utilisation de la commande de connexion Hugging Face.
* **”Jeton invalide” ou “Erreur d’Authentification” :**
* **Fautes de frappe :** Vérifiez que vous avez copié et collé le jeton correctement. Il n’y a pas d’espaces ni de caractères supplémentaires.
* **Jeton Expiré :** Bien que les jetons 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 jeton (`read`, `write`) est-il suffisant pour l’opération que vous essayez d’effectuer ? Par exemple, un jeton `read` ne peut pas envoyer des modèles.
* **”Commande introuvable : 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 jeton pourrait ne pas être automatiquement pris en compte.
* **Priorité des Variables d’Environnement :** Si vous définissez également `HF_TOKEN` comme variable d’environnement, cela pourrait avoir la priorité sur le jeton mis en cache.
* **Corruption de Cache :** Dans de rares cas, le fichier de cache du jeton peut être corrompu. Vous pouvez essayer de supprimer le fichier (`~/.cache/huggingface/token`) et d’exécuter à nouveau `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`.
Bonnes Pratiques de Sécurité pour la CLI de Connexion Hugging Face
* **Moins de Privilèges :** Créez toujours des jetons avec les autorisations minimales nécessaires (`read` vs. `write`).
* **Nom des Jetons :** Donnez à vos jetons des noms descriptifs afin de savoir à quoi ils servent.
* **Rotation des Jetons :** Pour les applications critiques, envisagez de faire tourner vos jetons périodiquement.
* **Variables d’Environnement pour la Production :** Ne jamais coder des jetons en dur dans votre code, surtout en production. Utilisez des variables d’environnement (`HF_TOKEN`) ou un système de gestion des secrets.
* **Stockage Sécurisé :** La CLI de connexion Hugging Face stocke le jeton dans le répertoire de cache de votre utilisateur. Assurez-vous que ce répertoire est protégé par des permissions système standard.
* **Éviter le Root :** Ne pas exécuter `huggingface-cli login` en tant qu’utilisateur root sauf si absolument nécessaire, et comprendre les implications de sécurité.
Conclusion
La CLI de connexion Hugging Face est un outil fondamental pour quiconque cherche à intégrer des modèles et des datasets Hugging Face dans ses flux de travail automatisés. En comprenant comment générer des jetons 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 en IA. Adoptez la CLI pour son efficacité et sa puissance, et débloquez 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 jeton d’accès (que vous générez sur le site Web de Hugging Face) et enregistre ensuite ce jeton de manière sécurisée dans un fichier de cache local. Cela permet à vos scripts Python et autres opérations `huggingface_hub` d’accéder à des modèles privés, des datasets ou d’effectuer des actions comme l’envoi de modèles sans avoir besoin de ré-entrer votre jeton à chaque fois.
Q2 : Où puis-je obtenir le jeton nécessaire pour `huggingface-cli login`?
Vous générez le jeton depuis les paramètres de votre compte Hugging Face. Connectez-vous à huggingface.co, allez dans vos “Paramètres,” puis naviguez vers “Jetons d’Accès.” Cliquez sur “Nouveau jeton,” 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 jeton 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 quand même 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 jeton d’accès. La bibliothèque `huggingface_hub` le prendra automatiquement en compte. 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 jeton que vous avez utilisé a les permissions correctes (par exemple, un rôle `read` pour le téléchargement). Ensuite, 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 remplacer le jeton mis en cache, vérifiez donc sa valeur. Enfin, vérifiez à nouveau 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: