Hugging Face Hub: Finding and Using Models

1. Overview

Hugging Face Hub is the largest repository of machine learning models, datasets, and demos available today. This guide shows you how to find the right model (instead of guessing the name), read model cards to avoid license or architecture mistakes, then call that model in two ways: running locally with Python and calling via Inference API from a Spring Boot application. By the end, you’ll be able to integrate an NLP model into your Java service without needing to host a GPU yourself.

2. What is Hugging Face Hub

The Hub stores three main types of resources:

• Models: pre-trained weights with a model card describing how to use them.
• Datasets: data for training, fine-tuning, or benchmarking.
• Spaces: live demos running directly in your browser (Gradio, Streamlit).

Each model has a model_id in the format organization/model-name, for example distilbert-base-uncased-finetuned-sst-2-english. This model_id is what you’ll use in your code, not the display name shown on the UI.

3. Finding Models on the Hub

3.1. Via Web Interface

The Hub homepage provides filters for task (text-classification, translation, image-segmentation…), library (transformers, sentence-transformers, timm…), license, and language. Sorting by “Most downloads” or “Trending” usually gives more stable results than selecting the newest models — newer models haven’t necessarily been verified by enough users yet.

3.2. Via huggingface_hub (Python)

When you need to find models programmatically (for example, to automatically select the smallest model that meets your requirements), use 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 filters by keywords in the model name/tags, sort="downloads" combined with direction=-1 ranks the most popular models first, and limit=5 restricts the results. The output looks like:

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

Note: download count doesn’t necessarily mean the highest quality for your specific use case — it only reflects general popularity. Always test on real data before making a final decision.

4. Read the Model Card Before Using

Each model includes a README.md file displayed as a model card, which contains:

• Task: what the model was trained for (classification, translation, text generation…).
• License: apache-2.0, mit, or cc-by-nc (non-commercial — can’t be used for commercial products).
• Gated model: some models require you to log in and be approved by the owner before downloading (typically large or sensitive models).

Quickly check the license and gated status via 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 means you need a personal token and must have been granted access; otherwise the request will return a 401/403 error.

5. Running Models Locally with transformers

For smaller models, the fastest way to experiment is using 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 automatically downloads weights from the Hub to your local cache (~/.cache/huggingface), loads the corresponding tokenizer, and returns results as a list of dictionaries. The first run will be slow because it needs to download the model file — check the model size on the Hub page before downloading if you’re working in a bandwidth or disk-limited environment.

6. Calling Models from Spring Boot via Inference API

When your main application is written in Java, you don’t need to host the model yourself — Hugging Face provides an Inference API (HTTP) for many popular models. Simply make REST calls with your personal token.

<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 is auto-configured by Spring Boot; you just need to set the baseUrl and Authorization header.
• uri("/{model}", model) builds a URL like .../models/distilbert-base-uncased-finetuned-sst-2-english.
• The Inference API response for the text-classification task is a nested array ([[{...}]]), so the return type is SentimentResult[][].

Try it out:

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

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

Test parsing response

Since the actual response depends on network conditions, you should separate JSON parsing into a test that doesn’t require calling the real API:

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

This test ensures that the SentimentResult record correctly maps the label and score fields without depending on network connectivity or a valid token.

7. Common Errors and When Not to Use Inference API

• 503 Service Unavailable on first call: the model hasn’t been “warmed up” on the free tier server yet. Hugging Face includes an estimated_time field — you should retry after a few seconds rather than treating it as a real error.
• 429 Too Many Requests: the free tier has strict rate limits. For stable production traffic, consider using Inference Endpoints (dedicated, paid) instead of the free API.
• Gated model but access not yet approved: you get a 403 error even with a valid token — go to the model page, click “Request access,” and wait for approval.
• License incompatible with commercial use: many models fine-tuned from Llama or datasets with non-commercial restrictions come with special terms; read the license section on the model card carefully before adding it to your product.

Note: don’t use the free Inference API for systems that require stable low latency or SLA — it’s suitable for experimentation, demos, or low traffic. For large workloads, host the model locally using transformers/text-generation-inference or use paid Inference Endpoints.

8. Conclusion

Hugging Face Hub gives you a clear workflow: find models via the UI or huggingface_hub, read the model card to check the task, license, and gated status, then choose the appropriate way to use it — run locally with pipeline when you need full control, or call Inference API from Spring Boot when you want quick integration into your existing Java system. The key point is to always check the license and rate limits before deploying a model to production.