Hugging Face Hub: buscar y usar modelos

1. Descripción general

Hugging Face Hub es el repositorio más grande actualmente para modelos, conjuntos de datos y demostraciones de machine learning. Este artículo te ayuda a saber cómo encontrar el modelo correcto que necesitas (en lugar de adivinar el nombre), leer la tarjeta del modelo para evitar usar la licencia equivocada o la arquitectura incorrecta, y luego invocar ese modelo de dos formas: ejecutarlo localmente con Python e invocarlo a través de la Inference API desde una aplicación Spring Boot. Después de leerlo, serás capaz de integrar un modelo NLP en un servicio Java sin necesidad de hostear tu propio GPU.

2. ¿Qué es Hugging Face Hub?

Hub almacena tres tipos principales de recursos:

• Modelos: pesos ya entrenados, con una tarjeta del modelo que describe cómo usarlo.
• Conjuntos de datos: datos para entrenar, ajustar o hacer pruebas de rendimiento.
• Espacios: demostraciones que se ejecutan directamente en el navegador (Gradio, Streamlit).

Cada modelo tiene un model_id con formato organización/nombre-modelo, por ejemplo distilbert-base-uncased-finetuned-sst-2-english. Este model_id es lo que usarás en el código, no el nombre mostrado en la interfaz de usuario.

3. Buscar un modelo en Hub

3.1. A través de la interfaz web

La página de inicio del Hub tiene filtros por task (text-classification, translation, image-segmentation…), library (transformers, sentence-transformers, timm…), license e language. Ordenar por “Most downloads” o “Trending” generalmente da resultados más confiables que elegir el modelo más reciente — los modelos más nuevos aún no tienen suficientes usuarios que los hayan probado.

3.2. A través de huggingface_hub (Python)

Cuando necesitas buscar un modelo a través de un script (por ejemplo, para elegir automáticamente el modelo más pequeño que cumpla los requisitos), usa 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 palabras clave en el nombre/etiqueta, sort="downloads" junto con direction=-1 ordena los modelos más populares primero, limit=5 limita los resultados. La salida es similar a:

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

Nota: la cantidad de descargas no significa la mejor calidad para tu caso de uso — solo refleja la popularidad general. Siempre prueba con datos reales antes de decidir.

4. Lee la tarjeta del modelo antes de usarlo

Cada modelo tiene un archivo README.md que se muestra como una tarjeta del modelo, que contiene:

• Task: la tarea para la que se entrenó el modelo (clasificación, traducción, generación de texto…).
• License: apache-2.0, mit, o cc-by-nc (non-commercial — no se puede usar para productos comerciales).
• Gated model: algunos modelos requieren que inicies sesión y que el propietario apruebe antes de descargar (generalmente modelos grandes o sensibles).

Verifica rápidamente la licencia y el estado gated con la 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 necesitas un token personal y que te ha sido otorgado acceso, de lo contrario, la solicitud devolverá un error 401/403.

5. Ejecutar un modelo localmente con transformers

Para modelos pequeños, la forma más rápida de experimentar es usando 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 descarga automáticamente los pesos desde Hub al caché local (~/.cache/huggingface), carga el tokenizador correspondiente, y devuelve los resultados como una lista de diccionarios. La primera ejecución será lenta porque debe descargar los archivos del modelo — verifica el tamaño del modelo en la página del Hub antes de descargarlo si te encuentras en un entorno con ancho de banda/disco limitado.

6. Invocar un modelo desde Spring Boot a través de Inference API

Cuando tu aplicación principal está escrita en Java, no necesitas hostear el modelo tú mismo — Hugging Face proporciona Inference API (HTTP) para muchos modelos populares. Solo necesitas hacer una llamada REST con tu token personal.

<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 es configurado automáticamente por Spring Boot, solo necesitas establecer baseUrl y el header Authorization.
• uri("/{model}", model) construye la URL de la forma .../models/distilbert-base-uncased-finetuned-sst-2-english.
• La respuesta de Inference API para la tarea text-classification es un array anidado ([[{...}]]), por lo que el tipo de retorno es SentimentResult[][].

Pruébalo:

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

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

Test parsing response

Dado que la respuesta real depende de la red, deberías separar la parte de análisis JSON para hacer pruebas sin necesidad de llamar a la API real:

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

Esta prueba asegura que el record SentimentResult mapee correctamente los campos label/score sin depender de la conexión de red o de un token válido.

7. Errores comunes y cuándo no usar Inference API

• 503 Service Unavailable en la primera llamada: el modelo aún no ha sido “calentado” en el servidor de capa gratuita. Hugging Face proporciona un campo estimated_time — deberías reintentar después de unos segundos en lugar de considerarlo un error real.
• 429 Too Many Requests: la capa gratuita tiene límites de velocidad bastante estrictos. Para tráfico de producción estable, considera Inference Endpoints (dedicados, de pago) en lugar de la API gratuita.
• Modelo gated pero aún no aprobado: error 403 aunque el token sea válido — necesitas ir a la página del modelo, hacer clic en “Request access” y esperar la aprobación.
• La licencia no es adecuada para fines comerciales: muchos modelos fine-tuned de Llama o de conjuntos de datos no comerciales vienen con términos separados, lee cuidadosamente la sección de licencia en la tarjeta del modelo antes de incorporarlo a tu producto.

Nota: no uses Inference API gratuita para sistemas que requieren latencia baja consistente o SLA — es adecuada para experimentación, demostración o tráfico bajo. Para cargas de trabajo grandes, hostea el modelo localmente con transformers/text-generation-inference o usa Inference Endpoints de pago.

8. Conclusión

Hugging Face Hub te proporciona un proceso claro: buscar modelos a través de la interfaz de usuario o huggingface_hub, leer la tarjeta del modelo para verificar task/license/gated, y luego elegir la forma de uso adecuada — ejecuta localmente con pipeline cuando necesites control total, o invoca Inference API desde Spring Boot cuando quieras integrar rápidamente en tu sistema Java existente. El punto clave es siempre verificar la licencia y los límites de velocidad antes de poner el modelo en producción.