Comment configurer Hugging Face Hub : Guide pratique

TL;DR

• Créez un compte gratuit et générez un jeton d'accès sur huggingface.co
• Installez le SDK et l'interface en ligne de commande huggingface_hub : pip install --upgrade huggingface_hub
• Téléchargez des modèles avec snapshot_download() ou utilisez l'API d'inférence gratuite
• Déployez des démonstrations en quelques minutes avec Spaces (Gradio/Streamlit)
• Publiez vos propres modèles avec push_to_hub() ou l'interface en ligne de commande

1. Créer un compte et un jeton

Hugging Face Hub utilise des jetons d'accès pour l'authentification. Voici comment en configurer un :

Étape 1 : S'inscrire

1. Rendez-vous sur huggingface.co/join
2. Saisissez votre adresse e-mail, votre nom d'utilisateur et votre mot de passe
3. Validez votre adresse e-mail (vérifiez votre boîte de réception)

Étape 2 : Générer un jeton d'accès

1. Accédez à huggingface.co/settings/tokens
2. Cliquez sur "Nouveau jeton"
3. Définissez un nom (par exemple, my-laptop-cli) et un rôle (sélectionnez "Write" pour un accès complet)
4. Cliquez sur "Générer un jeton"
5. Copiez le jeton immédiatement (il ne sera plus affiché par la suite)

Résultat attendu :

hf_abcdefghijklmnopqrstuvwxyz1234567890

Étape 3 : Enregistrer votre jeton en toute sécurité

# Enregistrer dans un fichier (Linux/macOS)
echo "hf_abcdefghijklmnopqrstuvwxyz1234567890" > ~/.huggingface/token

# Définir les permissions (Linux/macOS)
chmod 600 ~/.huggingface/token

Attention : Ne jamais commiter votre jeton dans Git. Ajoutez ~/.huggingface/token à votre fichier .gitignore.

2. Configurer huggingface-cli

L'interface en ligne de commande est le moyen le plus rapide d'interagir avec le Hub depuis votre terminal.

Installer l'interface en ligne de commande

pip install --upgrade "huggingface_hub[cli]"

Se connecter

huggingface-cli login

Résultat attendu :

    _|    _|  _|    _|    _|_|_|    _|_|_|  _|_|_|  _|      _|
    _|    _|  _|    _|  _|        _|          _|    _|_|    _|
    _|_|_|_|  _|    _|  _|  _|_|  _|  _|_|    _|    _|  _|  _|
    _|    _|  _|    _|  _|    _|  _|    _|    _|    _|    _|_
    _|    _|    _|_|      _|_|_|    _|_|_|  _|_|_|  _|      _|

Pour vous connecter, `huggingface_hub` nécessite un jeton généré depuis https://huggingface.co/settings/tokens.
Jeton :

Collez votre jeton et appuyez sur Entrée.

Erreur courante :

ValueError: Le jeton est invalide. Veuillez réessayer.

Solution : Régénérez votre jeton et assurez-vous de l'avoir copié correctement.

3. Télécharger et utiliser des modèles

Hugging Face Hub héberge plus de 500 000 modèles (chiffres de 2026) Statistiques Hugging Face Hub. Voici comment les utiliser :

Option 1 : Téléchargement avec snapshot_download

from huggingface_hub import snapshot_download

# Télécharger un modèle (par exemple, "bert-base-uncased")
model_path = snapshot_download(
    repo_id="bert-base-uncased",
    local_dir="./bert-base-uncased",
    local_dir_use_symlinks=False  # Éviter les liens symboliques pour la portabilité
)

print(f"Modèle téléchargé dans : {model_path}")

Résultat attendu :

Modèle téléchargé dans : ./bert-base-uncased

Option 2 : Utilisation avec Transformers

from transformers import AutoTokenizer, AutoModel

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased")

inputs = tokenizer("Bonjour, le monde !", return_tensors="pt")
outputs = model(**inputs)
print(outputs.last_hidden_state.shape)

Résultat attendu :

torch.Size([1, 4, 768])

Attention : Les modèles volumineux (par exemple, meta-llama/Llama-3-70b) peuvent nécessiter plus de 100 Go d'espace disque. Utilisez ignore_patterns=["*.bin"] dans snapshot_download pour ignorer les poids.

4. API d'inférence (niveau gratuit)

L'API d'inférence vous permet d'exécuter des modèles sans les télécharger. Le niveau gratuit inclut 1 000 requêtes par jour Documentation API d'inférence.

Exemple : Génération de texte

import requests

API_URL = "https://api-inference.huggingface.co/models/mistralai/Mistral-7B-v0.1"
headers = {"Authorization": "Bearer hf_abcdefghijklmnopqrstuvwxyz1234567890"}

def query(payload):
    response = requests.post(API_URL, headers=headers, json=payload)
    return response.json()

output = query({
    "inputs": "Explique l'IA à un enfant de 5 ans :",
    "parameters": {"max_new_tokens": 50}
})

print(output[0]["generated_text"])

Résultat attendu :

L'IA, c'est comme un ami robot très intelligent qui apprend dans les livres et les jeux pour nous aider à faire des choses amusantes, comme dessiner ou raconter des histoires !

Limites de débit

Attention : Les requêtes en niveau gratuit peuvent être mises en file d'attente pendant les périodes de pointe. Passez à l'offre Pro pour un accès prioritaire.

5. Spaces pour les démonstrations

Spaces sont des applications web interactives (Gradio/Streamlit) hébergées sur Hugging Face. Parfaites pour des démonstrations ou des outils internes.

Étape 1 : Créer un Space

1. Rendez-vous sur huggingface.co/spaces
2. Cliquez sur "Créer un nouveau Space"
3. Sélectionnez :
   • Nom : my-first-demo
   • Licence : MIT
   • Matériel : CPU (gratuit) ou A10G (payant, 0,50 $/heure)
   • SDK : Gradio (le plus simple pour les débutants)
4. Cliquez sur "Créer un Space"

Étape 2 : Ajouter une application simple

Remplacez le contenu de app.py par :

import gradio as gr

def greet(name):
    return f"Bonjour {name} !"

demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo.launch()

Étape 3 : Déployer

1. Cliquez sur "Commit" pour pousser les modifications
2. Attendez 30 à 60 secondes que l'application se construise
3. Partagez l'URL de votre Space (par exemple, https://hf.co/spaces/votre-nom-utilisateur/my-first-demo)

Attention : Les Spaces gratuits s'arrêtent après 30 minutes d'inactivité. Utilisez la fonction "Always On" (payante) pour éviter cela.

6. Publier vos propres modèles

Partagez vos modèles avec le monde entier (ou gardez-les privés).

Option 1 : Utilisation de l'interface en ligne de commande

# Créer un nouveau dépôt
huggingface-cli repo create my-awesome-model --type model

# Cloner le dépôt
git lfs install
git clone https://huggingface.co/votre-nom-utilisateur/my-awesome-model
cd my-awesome-model

# Ajouter vos fichiers de modèle (par exemple, des poids PyTorch)
cp /chemin/vers/votre/modèle/* .

# Commiter et pousser
git add .
git commit -m "Ajout de mon super modèle"
git push

Option 2 : Utilisation du SDK Python

from huggingface_hub import HfApi

api = HfApi()
api.upload_file(
    path_or_fileobj="/chemin/vers/pytorch_model.bin",
    path_in_repo="pytorch_model.bin",
    repo_id="votre-nom-utilisateur/my-awesome-model",
    repo_type="model",
)

Attention : Les fichiers volumineux (>5 Go) peuvent expirer. Utilisez huggingface_hub avec des téléchargements par morceaux :

from huggingface_hub import upload_file

upload_file(
    path_or_fileobj="/chemin/vers/large-model.bin",
    path_in_repo="large-model.bin",
    repo_id="votre-nom-utilisateur/my-awesome-model",
    repo_type="model",
    chunk_size=10 * 1024 * 1024,  # Morceaux de 10 Mo
)

7. Démarrage rapide avec la bibliothèque Transformers

La bibliothèque transformers est le moyen le plus simple d'utiliser les modèles Hugging Face.

Installer Transformers

pip install --upgrade transformers

Exemple : Classification de texte

from transformers import pipeline

classifier = pipeline("text-classification", model="distilbert-base-uncased-finetuned-sst-2-english")
result = classifier("J'adore Hugging Face Hub !")
print(result)

Résultat attendu :

[{'label': 'POSITIVE', 'score': 0.9998}]

Exemple : Classification d'images

from transformers import pipeline

classifier = pipeline("image-classification", model="google/vit-base-patch16-224")
result = classifier("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/cat.png")
print(result)

Résultat attendu :

[{'label': 'tabby cat', 'score': 0.98}]

Attention : Certains modèles nécessitent des dépendances spécifiques (par exemple, torch pour les modèles PyTorch). Installez-les avec :

pip install torch tensorflow  # Pour les modèles PyTorch/TensorFlow

Prochaines étapes

1. Explorer les modèles : Parcourez huggingface.co/models et testez 3 modèles avec l'API d'inférence.
2. Déployer un Space : Créez une application Gradio pour votre modèle préféré (par exemple, un chatbot ou un générateur d'images).
3. Contribuer : Publiez un modèle affiné ou un jeu de données pour partager avec la communauté.

Pour les équipes qui souhaitent mettre à l'échelle leurs workflows d'IA, Hyperion Consulting propose des outils et des services de conseil de bout en bout pour optimiser vos déploiements sur Hugging Face.