Hugging Face Hub : trouver et utiliser des modèles

1. Aperçu

Hugging Face Hub est le plus grand référentiel actuel pour les modèles, datasets et démos de machine learning. Cet article vous montre comment trouver le bon modèle (plutôt que de deviner son nom), consulter sa model card pour éviter les erreurs de licence ou d’architecture, puis l’utiliser de deux façons : l’exécuter localement avec Python ou l’appeler via l’Inference API depuis une application Spring Boot. Au terme de la lecture, vous saurez intégrer un modèle NLP dans un service Java sans héberger votre propre GPU.

2. Qu’est-ce que Hugging Face Hub

Le Hub stocke trois types de ressources principales :

• Models : des poids pré-entraînés, accompagnés d’une model card décrivant comment les utiliser.
• Datasets : des données pour l’entraînement/le fine-tuning ou l’évaluation (benchmark).
• Spaces : des démos exécutées directement dans le navigateur (Gradio, Streamlit).

Chaque modèle a un model_id de la forme organisation/nom-modèle, par exemple distilbert-base-uncased-finetuned-sst-2-english. C’est ce model_id que vous utiliserez dans votre code, non le nom affiché dans l’interface.

3. Trouver un modèle sur le Hub

3.1. Via l’interface web

La page d’accueil du Hub propose des filtres par task (text-classification, translation, image-segmentation…), library (transformers, sentence-transformers, timm…), license et language. Trier par « Most downloads » ou « Trending » donne généralement des résultats plus fiables que de choisir le modèle le plus récent — les nouveaux modèles n’ont pas forcément été validés par suffisamment d’utilisateurs.

3.2. Via huggingface_hub (Python)

Quand vous avez besoin de trouver un modèle par script (par exemple pour choisir automatiquement le plus petit modèle répondant à vos critères), utilisez HfApi :

pip install huggingface_hub

from huggingface_hub import HfApi

api = HfApi()
models = api.list_models(
    search="sentiment",
    library="transformers",
    sort="downloads",
    direction=-1,
    limit=5,
)

for m in models:
    print(m.id, m.downloads)

search filtre par mot-clé dans le nom/les tags, sort="downloads" associé à direction=-1 classe les modèles les plus populaires en premier, limit=5 limite les résultats. La sortie ressemble à :

distilbert-base-uncased-finetuned-sst-2-english 5123456
cardiffnlp/twitter-roberta-base-sentiment-latest 2876543
nlptown/bert-base-multilingual-uncased-sentiment 1987654
...

Remarque : le nombre de téléchargements ne signifie pas que c’est le meilleur modèle pour votre problématique — il reflète juste sa popularité générale. Testez toujours sur vos données réelles avant de prendre une décision.

4. Consulter la model card avant d’utiliser

Chaque modèle possède un fichier README.md affiché sous forme de model card, contenant :

• Task : la tâche pour laquelle le modèle a été entraîné (classification, traduction, génération de texte…).
• License : apache-2.0, mit ou cc-by-nc (non-commercial — pas d’utilisation pour un produit commercial).
• Gated model : certains modèles vous demandent de vous connecter et d’être approuvé par le propriétaire avant de pouvoir les télécharger (généralement les gros modèles ou les modèles sensibles).

Vérifiez rapidement la licence et l’état gated via l’API :

from huggingface_hub import model_info

info = model_info("meta-llama/Llama-3.1-8B")
print(info.gated, info.tags)

True ['text-generation', 'license:llama3.1']

gated=True signifie que vous avez besoin d’un token personnel et que vous devez avoir été approuvé pour accéder — sinon, la requête renverra une erreur 401/403.

5. Exécuter un modèle localement avec transformers

Pour les modèles petits, la façon la plus rapide de tester est d’utiliser pipeline :

pip install transformers torch

from transformers import pipeline

classifier = pipeline(
    "sentiment-analysis",
    model="distilbert-base-uncased-finetuned-sst-2-english",
)
result = classifier("Hugging Face Hub makes finding models easy!")
print(result)

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

pipeline télécharge automatiquement les poids du Hub vers votre cache local (~/.cache/huggingface), charge le tokenizer correspondant et retourne le résultat sous forme de liste de dictionnaires. La première exécution sera lente car elle doit télécharger les fichiers du modèle — consultez la taille du modèle sur la page du Hub avant de le télécharger si vous travaillez dans un environnement avec une bande passante ou un espace disque limités.

6. Appeler un modèle depuis Spring Boot via l’Inference API

Quand votre application principale est écrite en Java, vous n’avez pas besoin d’héberger le modèle vous-même — Hugging Face fournit une Inference API (HTTP) pour de nombreux modèles populaires. Il suffit d’appeler l’API REST avec votre token personnel.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

huggingface.api-token=${HF_API_TOKEN}
huggingface.model=distilbert-base-uncased-finetuned-sst-2-english

@Service
public class SentimentAnalysisService {

    private final RestClient restClient;
    private final String model;

    public SentimentAnalysisService(RestClient.Builder builder,
                                     @Value("${huggingface.api-token}") String token,
                                     @Value("${huggingface.model}") String model) {
        this.model = model;
        this.restClient = builder
                .baseUrl("https://api-inference.huggingface.co/models")
                .defaultHeader("Authorization", "Bearer " + token)
                .build();
    }

    public List<SentimentResult> analyze(String text) {
        SentimentResult[][] response = restClient.post()
                .uri("/{model}", model)
                .body(Map.of("inputs", text))
                .retrieve()
                .body(SentimentResult[][].class);

        return response == null ? List.of() : List.of(response[0]);
    }

    public record SentimentResult(String label, double score) {}
}

• RestClient.Builder est configuré automatiquement par Spring Boot — il suffit de définir le baseUrl et le header Authorization.
• uri("/{model}", model) construit une URL de la forme .../models/distilbert-base-uncased-finetuned-sst-2-english.
• La réponse de l’Inference API pour la tâche text-classification est un tableau imbriqué ([[{...}]]), donc le type de retour est SentimentResult[][].

Essayez d’appeler :

List<SentimentAnalysisService.SentimentResult> results =
        sentimentAnalysisService.analyze("I love this library!");

[SentimentResult[label=POSITIVE, score=0.9997]]

Tester l’analyse de la réponse

Puisque la réponse réelle dépend du réseau, vous devriez séparer la partie parsing JSON pour tester sans appeler l’API réelle :

import com.fasterxml.jackson.databind.ObjectMapper;
import static org.assertj.core.api.Assertions.assertThat;

class SentimentResultParsingTest {

    @Test
    void shouldParseInferenceApiResponse() throws Exception {
        String json = """
            [[{"label":"POSITIVE","score":0.9998}]]
            """;
        ObjectMapper mapper = new ObjectMapper();

        SentimentAnalysisService.SentimentResult[][] result =
                mapper.readValue(json, SentimentAnalysisService.SentimentResult[][].class);

        assertThat(result[0][0].label()).isEqualTo("POSITIVE");
        assertThat(result[0][0].score()).isGreaterThan(0.99);
    }
}

Ce test garantit que le record SentimentResult mappe correctement les champs label/score indépendamment de la connexion réseau ou du token valide.

7. Erreurs courantes et quand ne pas utiliser l’Inference API

• 503 Service Unavailable lors du premier appel : le modèle n’a pas encore été « warm up » sur le serveur du tier gratuit. Hugging Face retourne un champ estimated_time — vous devriez réessayer après quelques secondes plutôt que de traiter cela comme une erreur réelle.
• 429 Too Many Requests : le tier gratuit a des limites de débit assez strictes. Pour un trafic de production stable, envisagez les Inference Endpoints (dédiés, payants) plutôt que l’API gratuite.
• Modèle gated mais non approuvé : erreur 403 même avec un token valide — vous devez accéder à la page du modèle, cliquer sur « Request access » et attendre l’approbation.
• Licence incompatible avec un usage commercial : de nombreux modèles fine-tune à partir de Llama ou de datasets non-commercial sont assortis de conditions particulières — lisez attentivement la section licence de la model card avant de les utiliser dans un produit.

Remarque : n’utilisez pas l’Inference API gratuite pour les systèmes nécessitant une latence faible stable ou un SLA — elle convient pour l’expérimentation, les démos ou un trafic faible. Pour de grandes charges de travail, hébergez le modèle localement avec transformers/text-generation-inference ou utilisez les Inference Endpoints payants.

8. Conclusion

Hugging Face Hub vous offre un processus clair : trouvez le modèle via l’interface ou huggingface_hub, consultez sa model card pour vérifier la tâche/licence/statut gated, puis choisissez comment l’utiliser — exécutez-le localement avec pipeline si vous avez besoin d’un contrôle total, ou appelez l’Inference API depuis Spring Boot pour une intégration rapide dans votre système Java existant. L’essentiel est de toujours vérifier la licence et les limites de débit avant de mettre le modèle en production.