Jeton Hugging Face : le créer, l’utiliser et le sécuriser

Un jeton d’accès utilisateur Hugging Face, ou User Access Token, permet à une application de s’authentifier auprès de Hugging Face avec les autorisations que vous choisissez. Dans un tutoriel, vous pouvez aussi rencontrer les termes « clé API Hugging Face » ou « HF token ». Pour accéder au Hub, ils désignent généralement le jeton que vous gérez dans les paramètres de votre compte.

Commencez par définir l’opération à effectuer : télécharger un modèle à accès restreint, envoyer des fichiers ou appeler un service d’inférence. Ce choix détermine les autorisations nécessaires. Un jeton identifie votre compte ; il ne peut pas lui donner des droits qu’il ne possède pas.

Comment créer un jeton Hugging Face

1. Connectez-vous à votre compte Hugging Face et ouvrez les paramètres Access Tokens. Cette rubrique est aussi accessible dans la barre latérale des paramètres.

2. Cliquez sur New token. Donnez-lui un nom qui indique son usage, par exemple telechargement-modele-portable.

3. Choisissez un rôle. Pour une application en production, commencez par les autorisations fine-grained, qui permettent de limiter précisément les droits.

4. Sélectionnez les ressources et les actions dont l’application a besoin. N’accordez pas de droits d’écriture à une tâche de téléchargement uniquement pour simplifier sa configuration.

5. Créez le jeton et enregistrez sa valeur dans un gestionnaire de mots de passe ou dans le gestionnaire de secrets de l’application.

6. Testez l’opération prévue avant d’intégrer le jeton dans un processus plus long.

Ne placez pas le jeton dans des documents partagés, des captures d’écran ou du code source. Les exemples ci-dessous récupèrent la valeur depuis une invite masquée ou une variable d’environnement ; ils ne contiennent aucun véritable jeton.

Choisir les autorisations du jeton

Hugging Face documente trois rôles pour les jetons d’accès utilisateur :

• Fine-grained : limite l’accès aux ressources et aux autorisations sélectionnées. Ce rôle convient à une application qui utilise uniquement un modèle ou un ensemble précis de dépôts.

• Read : permet de lire les dépôts de modèles et de jeux de données auxquels votre compte a accès. Il ne permet pas d’y envoyer du contenu.

• Write : permet aussi de modifier les dépôts sur lesquels votre compte dispose de droits d’écriture. Utilisez-le pour envoyer des modèles ou des jeux de données, ou pour mettre à jour le contenu d’un dépôt.

Un notebook qui télécharge les poids d’un modèle et une tâche qui envoie un modèle entraîné n’ont pas les mêmes besoins. Donnez-leur des jetons distincts pour pouvoir remplacer l’un sans modifier l’autre. Pour les requêtes d’inférence, vérifiez également l’autorisation décrite plus bas.

Se connecter avec la CLI Hugging Face

Installez ou mettez à jour la bibliothèque du Hub dans votre environnement Python, puis lancez la connexion en ligne de commande :

python -m pip install --upgrade huggingface_hub
hf auth login
hf auth whoami

Le parcours de connexion actuel de la CLI propose une connexion par navigateur ou la saisie d’un jeton d’accès. Pour utiliser le jeton à autorisations limitées que vous venez de créer, sélectionnez Paste an access token et suivez les instructions. Certaines versions plus anciennes demandent directement le jeton.

La connexion par navigateur vous demande d’ouvrir une URL et de valider un code court. Elle obtient un identifiant d’accès pour ce parcours : ne supposez pas qu’elle utilise le jeton fine-grained créé séparément.

La commande hf auth whoami affiche le nom d’utilisateur actif et permet de vérifier le compte utilisé sur votre machine. Si vous utilisez aussi Git en HTTPS, configurez un gestionnaire d’identifiants adapté avant d’y enregistrer le jeton. Celui-ci peut servir de mot de passe pour l’authentification Git ; évitez de l’insérer dans l’URL d’un dépôt.

hf auth logout supprime les jetons enregistrés localement, mais ne les révoque pas sur Hugging Face et ne supprime pas la variable d’environnement HF_TOKEN. Si un jeton est compromis, intervenez dans les paramètres de votre compte.

Utiliser un jeton en Python sans l’inscrire dans le code

Par défaut, les requêtes vers le Hub peuvent utiliser une connexion enregistrée. Dans un script local ou un notebook, une invite masquée permet de choisir explicitement un jeton sans laisser sa valeur dans le fichier source ou dans la sortie d’une cellule :

from getpass import getpass
from huggingface_hub import hf_hub_download

access_token = getpass("Hugging Face access token: ")
model_file = hf_hub_download(
    repo_id="YOUR_ACCOUNT/YOUR_MODEL",
    filename="config.json",
    token=access_token,
)

Remplacez le nom du dépôt et du fichier par ceux d’un fichier auquel vous avez accès. Cet exemple télécharge un seul fichier ; il ne charge pas de modèle et ne lance aucune inférence. La documentation de hf_hub_download détaille les paramètres du dépôt, de la révision et du jeton.

Pour un déploiement, utilisez le gestionnaire de secrets de la plateforme pour fournir HF_TOKEN au processus. Vous pouvez ensuite lire explicitement cette variable :

import os
from huggingface_hub import hf_hub_download

model_file = hf_hub_download(
    repo_id="YOUR_ACCOUNT/YOUR_MODEL",
    filename="config.json",
    token=os.environ["HF_TOKEN"],
)

Cette version échoue si la variable d’environnement est absente, ce qui rend l’erreur de configuration visible. Ne remplacez jamais cette lecture par un véritable jeton dans du code destiné à être partagé.

Quel jeton est prioritaire ?

Pour les méthodes du Hub qui acceptent ce paramètre, une chaîne passée explicitement avec token= est utilisée pour l’appel concerné. L’implémentation des en-têtes de requête de Hugging Face traite cette valeur avant de rechercher un jeton enregistré. Avec token=False, ces méthodes envoient la requête sans jeton.

Lorsque la bibliothèque recherche automatiquement les identifiants, HF_TOKEN est prioritaire sur le jeton enregistré sur le disque. Une ancienne valeur dans cette variable peut donc expliquer pourquoi le changement d’un jeton local semble sans effet. Les notebooks hébergés peuvent aussi fournir des identifiants grâce à leur propre gestionnaire de secrets : vérifiez également cette configuration.

Définissez les variables d’environnement du déploiement avant d’importer la bibliothèque. Pour vérifier la présence de HF_TOKEN sans révéler sa valeur, affichez uniquement un booléen :

import os
print(bool(os.environ.get("HF_TOKEN")))

Une variable d’environnement évite d’inscrire le jeton dans le fichier source, mais ne protège pas contre toutes les fuites. Évitez d’afficher l’environnement complet, de journaliser les en-têtes d’autorisation ou d’activer le traçage du shell autour des commandes qui manipulent des secrets.

Accéder aux dépôts privés et aux modèles à accès contrôlé

Un jeton valide ne suffit pas à lui seul. Pour lire un dépôt privé, votre compte doit y être autorisé et votre jeton doit couvrir cette ressource. Pour un modèle à accès contrôlé, dit gated, vous devez également suivre sa procédure de demande d’accès.

Ouvrez la page du modèle avec le compte auquel appartient le jeton. Consultez les conditions et les informations demandées, notamment le nom d’utilisateur et l’adresse e-mail communiqués à l’auteur du modèle, puis demandez l’accès. Certains auteurs approuvent les demandes automatiquement ; d’autres les examinent manuellement. Créer un autre jeton ne contourne pas une demande en attente ou refusée. La documentation sur les modèles à accès contrôlé décrit cette procédure et précise que les autorisations sont accordées individuellement aux utilisateurs.

Cette distinction compte lorsque vous suivez un tutoriel d’installation. Notre guide FLUX.1 [dev] et ComfyUI traite, par exemple, du téléchargement des fichiers du modèle dans une configuration plus large. Résolvez les problèmes d’accès au dépôt avant de chercher une cause liée à la mémoire du GPU ou à l’exécution du modèle.

Les règles de l’organisation peuvent ajouter une condition

Les organisations Team et Enterprise peuvent limiter les jetons autorisés à accéder à leurs ressources. Une organisation peut imposer des jetons fine-grained ou l’approbation d’un administrateur. Un jeton en attente ou refusé peut provoquer une réponse 403 même si vous êtes membre de l’organisation.

Vérifiez son statut et demandez à un administrateur de l’examiner si nécessaire. Selon les règles de gestion des jetons d’organisation, un refus peut être annulé par une approbation. La révocation au niveau de l’organisation est définitive pour cette organisation, mais ne révoque pas le jeton partout ailleurs. En cas de fuite, retirer l’accès à une seule organisation ne suffit donc pas.

Utiliser un jeton avec Hugging Face Inference Providers

Pour Hugging Face Inference Providers, créez un jeton fine-grained avec l’autorisation Make calls to Inference Providers. Le téléchargement depuis un dépôt et l’accès à l’inférence sont deux besoins distincts.

Lorsque votre gestionnaire de secrets fournit HF_TOKEN, le client Python peut le lire ainsi :

import os
from huggingface_hub import InferenceClient

client = InferenceClient(api_key=os.environ["HF_TOKEN"])

La création de ce client ne génère pas de réponse à elle seule. Choisissez un modèle et une tâche pris en charge, puis suivez l’exemple d’API correspondant. Le guide du premier appel API montre comment passer de l’exemple fourni pour un modèle à une requête authentifiée.

Une authentification réussie ne garantit ni la disponibilité du modèle choisi, ni les droits d’accès de votre compte, ni la prise en charge de la requête par vos crédits et limites disponibles. Lisez l’erreur renvoyée avant de modifier les autorisations du jeton.

Si vous hébergez vous-même le modèle, séparez les identifiants utilisés pour télécharger ses fichiers depuis le Hub de ceux dont vos clients se servent pour appeler votre serveur. Notre guide de l’inférence LLM en production présente les choix plus larges de déploiement et de contrôle d’accès.

Résoudre un problème de jeton

Avant de vous reconnecter ou de générer un autre jeton, identifiez l’opération qui échoue et lisez le message d’erreur complet :

• Le mauvais compte est actif : exécutez hf auth whoami dans l’environnement où la requête échoue. Vérifiez sa configuration HF_TOKEN et tout paramètre token= explicite.

• Le téléchargement depuis un dépôt privé ou à accès contrôlé échoue : vérifiez le nom du dépôt, les droits du compte, les autorisations du jeton et l’approbation de l’accès au modèle. Une connexion sur le site web n’authentifie pas un processus distinct sur un serveur.

• Une ressource de l’organisation renvoie une erreur 403 : vérifiez les exigences relatives aux jetons fine-grained et le statut d’approbation. Des droits d’écriture plus larges ne remplacent pas l’accord d’un administrateur.

• L’inférence échoue alors que les téléchargements fonctionnent : vérifiez l’autorisation d’inférence, la disponibilité du modèle et l’erreur renvoyée par le service. Un téléchargement réussi ne teste pas l’accès à l’inférence.

• Un jeton cesse de fonctionner après son remplacement : mettez à jour tous les environnements qui utilisaient l’ancienne valeur, notamment les secrets des notebooks, les paramètres de déploiement et les gestionnaires d’identifiants Git.

Un code de statut ne suffit pas à diagnostiquer toutes les erreurs. Conservez l’identifiant de requête et le texte de l’erreur pour le support, mais retirez les jetons et les en-têtes d’autorisation avant de partager les journaux.

Conserver, remplacer et révoquer les jetons d’accès

Utilisez un jeton distinct pour chaque application ou environnement, limitez ses autorisations et notez où il est utilisé. Ce registre doit indiquer son usage et son responsable, sans contenir le secret lui-même.

Lors d’un remplacement planifié, créez un nouveau jeton avec les autorisations nécessaires, mettez à jour l’application, vérifiez son fonctionnement, puis retirez l’ancien. Supprimez les jetons des applications que vous n’utilisez plus. Sur une machine partagée, protégez le compte et les fichiers qui contiennent des identifiants enregistrés localement.

Pour les processus d’intégration continue compatibles, vous pouvez aussi envisager Trusted Publishers de Hugging Face. Cette fonction échange l’identité OpenID Connect d’un fournisseur d’intégration continue contre un jeton du Hub à courte durée de vie. Elle peut ainsi éviter de stocker un jeton d’accès utilisateur de longue durée dans ce processus. Vérifiez le fournisseur pris en charge et les ressources couvertes avant de l’adopter.

Que faire en cas de fuite d’un jeton ?

1. Invalidez le jeton exposé dans les paramètres Access Tokens. Traitez une fuite présumée comme une exposition réelle ; n’attendez pas une preuve d’utilisation abusive.

2. Remplacez-le dans les applications qui doivent conserver l’accès, avec les autorisations les plus limitées adaptées à leur usage.

3. Examinez les dépôts et services auxquels il pouvait accéder, ainsi que les traces d’activité disponibles, pour repérer des utilisations inattendues.

4. Retirez sa valeur du code, des journaux, des sorties de notebooks et des autres emplacements concernés. Coordonnez le nettoyage de l’historique du dépôt avec les autres contributeurs si nécessaire.

Supprimer une ligne d’un dépôt n’invalide pas le jeton. Les recommandations de GitHub sur la suppression de données sensibles placent la révocation ou le remplacement avant le nettoyage de l’historique. D’autres personnes peuvent déjà posséder des copies du contenu d’origine.

Un jeton d’accès est-il la même chose qu’un token de modèle ?

Non. Un jeton d’accès est un identifiant d’authentification. Les tokens d’un modèle sont les unités qu’un modèle de langage traite pour lire ou générer du contenu. Sa fenêtre de contexte et sa consommation d’inférence par token concernent ce second sens. Créer un jeton d’accès ne modifie pas la fenêtre de contexte d’un modèle et ne donne pas un accès illimité à l’inférence.

Avant de mettre un processus en service, vérifiez le compte utilisé, testez l’opération exacte et assurez-vous que le jeton est stocké hors du code. Ces vérifications facilitent ensuite le diagnostic des erreurs d’autorisation et le remplacement des jetons.