Hugging Face Hub: Modelle finden und verwenden

1. Überblick

Hugging Face Hub ist das größte Lager für Modelle, Datensätze und Demos im Machine Learning. Dieser Artikel hilft dir, das richtige Modell zu finden (anstatt den Namen zu raten), Modellkarten zu lesen, um Lizenz- oder Architekturfehler zu vermeiden, und das Modell auf zwei Wegen aufzurufen: lokal mit Python ausführen oder über die Inference API aus einer Spring-Boot-Anwendung aufrufen. Danach kannst du ein NLP-Modell in einen Java-Service integrieren, ohne selbst eine GPU zu hosten.

2. Was ist Hugging Face Hub

Das Hub speichert drei Haupttypen von Ressourcen:

• Modelle: vorgelernte Gewichte mit Modellkarte, die beschreibt, wie sie verwendet werden.
• Datensätze: Daten zum Trainieren/Fine-Tunen oder Benchmarking.
• Spaces: Demo, die direkt im Browser läuft (Gradio, Streamlit).

Jedes Modell hat eine model_id der Form organisation/modellname, zum Beispiel distilbert-base-uncased-finetuned-sst-2-english. Diese model_id ist das, das du im Code verwenden wirst, nicht der angezeigte Name in der UI.

3. Modelle auf dem Hub suchen

3.1. Über die Web-Oberfläche

Die Hub-Startseite hat Filter für Task (text-classification, translation, image-segmentation…), Library (transformers, sentence-transformers, timm…), License und Language. Nach “Most downloads” oder “Trending” zu sortieren liefert normalerweise stabilere Ergebnisse, als die neuesten Modelle zu wählen — neue Modelle sind nicht unbedingt ausreichend von Benutzern verifiziert.

3.2. Über huggingface_hub (Python)

Wenn du Modelle per Skript suchen musst (zum Beispiel, um automatisch das kleinste Modell zu wählen, das Anforderungen erfüllt), verwende 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 filtert nach Schlüsselwörtern im Namen/Tag, sort="downloads" zusammen mit direction=-1 sortiert die beliebtesten Modelle oben, limit=5 begrenzt die Ergebnisse. Die Ausgabe ist ähnlich:

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

Hinweis: Die Anzahl der Downloads bedeutet nicht unbedingt die höchste Qualität für deine Aufgabe — es reflektiert nur die allgemeine Beliebtheit. Teste immer mit echten Daten, bevor du dich festlegst.

4. Modellkarte vor der Verwendung lesen

Jedes Modell hat eine Datei README.md, die als Modellkarte angezeigt wird und Folgendes enthält:

• Task: wofür das Modell trainiert wurde (Klassifizierung, Übersetzung, Textgenerierung…).
• License: apache-2.0, mit oder cc-by-nc (non-commercial — nicht für kommerzielle Produkte verwendbar).
• Gated Modelle: einige Modelle erfordern, dass du dich anmeldest und vom Besitzer genehmigt wirst, bevor du sie herunterladen kannst (normalerweise große oder sensible Modelle).

Überprüfe schnell Lizenz und Status per 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 bedeutet, dass du ein persönliches Token brauchst und Zugriff erhalten hast, sonst gibt die Anfrage einen Fehler 401/403 zurück.

5. Modell lokal mit transformers ausführen

Bei kleineren Modellen ist die schnellste Möglichkeit zum Testen die Verwendung von 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 lädt Gewichte automatisch vom Hub in den lokalen Cache (~/.cache/huggingface), lädt den entsprechenden Tokenizer und gibt Ergebnisse als Liste von Dicts zurück. Der erste Lauf wird langsam sein, da Modell-Dateien heruntergeladen werden müssen — überprüfe die Modellgröße auf der Hub-Seite, bevor du es herunterlädst, wenn du in einer Umgebung mit begrenzter Bandbreite oder Festplatte bist.

6. Modelle aus Spring Boot über Inference API aufrufen

Wenn die Hauptanwendung in Java geschrieben ist, musst du das Modell nicht selbst hosten — Hugging Face bietet Inference API (HTTP) für viele gängige Modelle. Du brauchst nur REST mit einem persönlichen Token aufzurufen.

<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 wird von Spring Boot automatisch konfiguriert, nur baseUrl und Authorization-Header setzen.
• uri("/{model}", model) baut die URL wie .../models/distilbert-base-uncased-finetuned-sst-2-english.
• Die Response der Inference API für die Task text-classification ist ein verschachteltes Array ([[{...}]]), daher ist der Rückgabetyp SentimentResult[][].

Zum Testen:

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

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

JSON-Response-Parsing testen

Da die tatsächliche Response vom Netzwerk abhängt, solltest du das Parsing vom Rest trennen, um zu testen, ohne die echte API aufzurufen:

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);
    }
}

Dieser Test stellt sicher, dass das Record SentimentResult die Felder label/score korrekt abbildet, ohne von Netzwerkverbindung oder gültigem Token abzuhängen.

7. Häufige Fehler und wann man keine Inference API verwenden sollte

• 503 Service Unavailable beim ersten Aufruf: Das Modell wurde noch nicht auf dem kostenlosen Tier “aufgewärmt”. Hugging Face gibt ein Feld estimated_time — du solltest nach einigen Sekunden erneut versuchen, anstatt dies als echten Fehler zu behandeln.
• 429 Too Many Requests: Der kostenlose Tier hat ziemlich strikte Rate-Limits. Bei stabilem Produktionsverkehr solltest du Inference Endpoints (dediziert, kostenpflichtig) statt der kostenlosen API verwenden.
• Gating-Modell, aber noch nicht genehmigt: Fehler 403, obwohl das Token gültig ist — gehe zur Modellseite, klicke auf “Request access” und warte auf Genehmigung.
• Lizenz nicht für kommerzielle Zwecke geeignet: Viele Modelle, die von Llama fein abgestimmt oder aus nicht-kommerziellen Datensätzen stammen, haben spezielle Bedingungen. Lese den Lizenzteil auf der Modellkarte sorgfältig, bevor du sie in dein Produkt aufnimmst.

Hinweis: Verwende die kostenlose Inference API nicht für Systeme, die niedriges Latenz und zuverlässiges SLA benötigen — sie eignet sich zum Experimentieren, für Demos oder geringen Traffic. Für große Workloads hoste das Modell lokal mit transformers/text-generation-inference oder verwende kostenpflichtige Inference Endpoints.

8. Fazit

Hugging Face Hub gibt dir ein klares Verfahren: Modelle über die UI oder huggingface_hub finden, Modellkarten lesen, um Task/Lizenz/Gating zu überprüfen, und dann eine passende Methode wählen — lokal mit pipeline ausführen, wenn du alles kontrollieren musst, oder Inference API aus Spring Boot aufrufen, wenn du schnell in ein bestehendes Java-System integrieren möchtest. Der wichtigste Punkt ist, die Lizenz und Rate-Limits zu überprüfen, bevor du ein Modell in die Produktion bringst.