Hugging Face Hub: encontrar e usar modelos

1. Visão geral

Hugging Face Hub é o maior repositório de modelos, datasets e demonstrações disponível atualmente para machine learning. Este artigo ajuda você a descobrir como encontrar o modelo certo que precisa (em vez de adivinhar o nome), ler o model card para evitar usar a licença errada ou arquitetura, e chamar esse modelo de duas formas: executando localmente com Python e chamando via Inference API de uma aplicação Spring Boot. Após ler, você conseguirá integrar um modelo NLP em um serviço Java sem precisar fazer host próprio de GPU.

2. O que é Hugging Face Hub

O Hub armazena três tipos principais de recursos:

• Models: pesos já treinados, acompanhados de um model card que descreve como usar.
• Datasets: dados para treinar/fazer fine-tune ou fazer benchmark.
• Spaces: demonstrações que rodam diretamente no navegador (Gradio, Streamlit).

Cada modelo tem um model_id na forma organização/nome-modelo, por exemplo distilbert-base-uncased-finetuned-sst-2-english. Este model_id é o que você vai usar no código, não o nome exibido na interface.

3. Encontrar modelos no Hub

3.1. Através da interface web

A página inicial do Hub tem filtros por task (text-classification, translation, image-segmentation…), library (transformers, sentence-transformers, timm…), license e language. Ordenar por “Most downloads” ou “Trending” geralmente dá resultados mais estáveis do que escolher o modelo mais recente — modelos novos podem não ter sido verificados por usuários suficientes.

3.2. Via huggingface_hub (Python)

Quando você precisa encontrar modelos via script (por exemplo para escolher automaticamente o modelo menor que atenda aos requisitos), 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 filtra por palavras-chave no nome/tags, sort="downloads" junto com direction=-1 ordena os modelos mais populares primeiro, limit=5 limita os resultados. Saída similar:

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

Nota: o número de downloads não significa a melhor qualidade para seu problema — apenas reflete o nível geral de popularidade. Sempre teste com dados reais antes de decidir.

4. Leia o model card antes de usar

Cada modelo tem um arquivo README.md exibido como um model card, que contém:

• Task: o modelo foi treinado para (classificação, tradução, geração de texto…).
• License: apache-2.0, mit, ou cc-by-nc (não-comercial — não pode ser usada para produtos comerciais).
• Gated model: alguns modelos exigem que você faça login e seja aprovado pelo proprietário antes de baixar (geralmente modelos grandes ou sensíveis).

Verifique rapidamente a licença e o status gated 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 significa que você precisa de um token pessoal e foi aprovado para acessar; caso contrário, a requisição retornará um erro 401/403.

5. Execute modelo localmente com transformers

Para modelos pequenos, a forma mais rápida de experimentar é usar 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 carrega automaticamente os pesos do Hub para o cache local (~/.cache/huggingface), carrega o tokenizer correspondente e retorna o resultado como uma lista de dicionários. A primeira execução será lenta porque precisa baixar o arquivo do modelo — verifique o tamanho do modelo na página do Hub antes de baixar se você está em um ambiente com largura de banda/disco limitado.

6. Chame modelo do Spring Boot via Inference API

Quando sua aplicação principal é escrita em Java, você não precisa fazer host próprio do modelo — Hugging Face fornece Inference API (HTTP) para muitos modelos populares. Basta fazer uma chamada REST com seu token pessoal.

<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 é configurada automaticamente pelo Spring Boot, apenas defina baseUrl e o header Authorization.
• uri("/{model}", model) constrói uma URL no formato .../models/distilbert-base-uncased-finetuned-sst-2-english.
• A resposta da Inference API para a tarefa text-classification é um array aninhado ([[{...}]]), então o tipo de retorno é SentimentResult[][].

Teste a chamada:

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

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

Teste de parsing da resposta

Como a resposta real depende da rede, você deve separar a parte de parsing JSON para testar sem chamar a API de verdade:

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

Este teste garante que o record SentimentResult mapeia corretamente os campos label/score sem depender de conexão de rede ou token válido.

7. Erros comuns e quando não usar Inference API

• 503 Service Unavailable na primeira chamada: o modelo ainda não foi “aquecido” no servidor de tier gratuito. Hugging Face retorna o campo estimated_time — você deve fazer retry após alguns segundos em vez de considerar isso um erro real.
• 429 Too Many Requests: o tier gratuito tem limites de taxa bem rigorosos. Com tráfego de produção estável, considere Inference Endpoints (dedicado, pago) em vez da API gratuita.
• Modelo gated mas não aprovado: erro 403 mesmo com token válido — você precisa ir à página do modelo, clicar em “Request access” e esperar pela aprovação.
• Licença não adequada para fins comerciais: muitos modelos fine-tuned da Llama ou datasets não-comerciais vêm com termos especiais — leia cuidadosamente a seção de licença no model card antes de colocar em produção.

Nota: não use a Inference API gratuita para sistemas que exigem latência baixa consistente ou SLA — ela é adequada para experimentar, fazer demos ou tráfego baixo. Para grandes workloads, hospede o modelo localmente com transformers/text-generation-inference ou use Inference Endpoints pagos.

8. Conclusão

Hugging Face Hub oferece um processo claro: encontre o modelo através da interface ou huggingface_hub, leia o model card para verificar task/license/gated, e escolha a forma de uso apropriada — execute localmente com pipeline quando você precisa de controle total, ou chame a Inference API do Spring Boot quando quer integrar rápido em um sistema Java existente. O ponto crucial é sempre verificar a licença e os limites de taxa antes de colocar o modelo em produção.