Levantar un servidor vLLM en Hugging Face Jobs con un solo comando

Resumen rápido

Pueden poner en marcha un endpoint privado, compatible con la API de OpenAI, en la infraestructura de Hugging Face con un único comando. No necesitan aprovisionar servidores ni orquestadores como Kubernetes: pagan por uso del hardware y pueden consultar el modelo desde su laptop, un notebook o cualquier servicio que acepte la API de OpenAI.

Esto es especialmente útil para equipos en Latinoamérica que buscan validar modelos, hacer evaluaciones o pruebas de generación sin invertir en infraestructura propia.

Requisitos previos

• Tener un método de pago activo o saldo prepago en Hugging Face (Jobs factura por uso de hardware).
• Tener instalada la librería huggingface_hub versión 1.20.0 o superior:

pip install -U "huggingface_hub>=1.20.0"

• Haber iniciado sesión localmente: hf auth login.

Lanzar el servidor en un solo comando

En Hugging Face, hf jobs run actúa como un docker run sobre su infraestructura. El ejemplo usa la imagen oficial vllm/vllm-openai, solicita GPU con --flavor y expone el puerto de vLLM con --expose:

hf jobs run --flavor a10g-large --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000 --expose 8000

Ese comando enruta el puerto del contenedor a través del proxy público de Jobs y al iniciar imprime la URL donde estará accesible el servidor. El sistema devuelve un ID de job (por ejemplo 6a381ca1953ed90bfb947332) que deben conservar; lo usaremos como <job_id> en los ejemplos.

Denle un par de minutos al proceso para descargar pesos y arrancar. Cuando los logs muestren Application startup complete, el servicio está listo.

Consultar el endpoint desde cualquier lugar

vLLM habla la API de OpenAI. Cada petición necesita llevar un token de Hugging Face como Bearer token. El ejemplo más rápido es con curl:

curl https://<job_id>--8000.hf.jobs/v1/chat/completions \
  -H "Authorization: Bearer $(hf auth token)" \
  -H "Content-Type: application/json" \
  -d '{ "model": "Qwen/Qwen3-4B", "messages": [{"role": "user", "content": "Hello!"}], "chat_template_kwargs": {"enable_thinking": false} }'

La respuesta viene en formato JSON estilo OpenAI; el texto generado aparecerá en choices[0].message.content.

Desde Python pueden apuntar el cliente de OpenAI al URL expuesto y usar el token de HF como API key:

from huggingface_hub import get_token
from openai import OpenAI

client = OpenAI(
    base_url="https://<job_id>--8000.hf.jobs/v1",
    api_key=get_token(),
)

resp = client.chat.completions.create(
    model="Qwen/Qwen3-4B",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)

print(resp.choices[0].message.content)

Antes de hacer muchas pruebas, una comprobación rápida de salud es listar los modelos disponibles:

curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)"

Seguridad: el endpoint está protegido. Todas las peticiones deben llevar un token de Hugging Face con permiso de lectura sobre el namespace del job. Una visita directa desde un navegador será rechazada. No compartan la URL esperando que sea pública y nunca peguen su token en sitios no confiables.

Parar y limpiar recursos

Los Jobs se facturan por uso de hardware, así que detengan el servidor cuando terminen para ahorrar costos:

hf jobs cancel <job_id>

El parámetro --timeout que pasaron al crear el job es un seguro que lo detendrá automáticamente al cumplirse, pero cancelar explícitamente suele ser más barato. Por ejemplo, una flavor a10g-large cuesta lo indicado en la documentación (en el blog original se menciona un ejemplo de $1.50/hora); revisen hf jobs hardware para la lista de precios actualizada y seleccionen la flavor más pequeña que soporte su modelo.

Escalar a modelos grandes

El mismo patrón funciona para modelos mucho mayores: elijan una flavor con más GPUs y ordenen a vLLM que haga sharding con --tensor-parallel-size. Ejemplo para un modelo grande de la familia Qwen:

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3.5-122B-A10B \
    --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 \
    --max-model-len 32768 --max-num-seqs 256

Notas importantes:

• --tensor-parallel-size debe coincidir con el número de GPUs en la flavor (h200x2 → 2, h200x8 → 8).
• Para modelos grandes suele recomendarse usar flavors H200 por su relación costo/eficiencia.
• Algunos modelos requieren limitar la longitud de contexto y el número de secuencias concurrentes (por ejemplo --max-model-len y --max-num-seqs) para evitar errores de memoria.

Si el modelo falla con errores de out-of-memory o cache-block, bajar esos dos parámetros es el primer ajuste a probar.

Interactuar desde una interfaz (UI)

Si prefieren una ventana de chat en lugar de curl, pueden montar una interfaz ligera con Gradio que apunte al mismo endpoint. Para ciertos modelos, añadir --reasoning-parser deepseek_r1 al comando vllm serve permite que el “pensamiento” del modelo llegue como un campo separado, lo cual resulta útil al depurar razonamiento.

La idea general es ejecutar localmente unas pocas líneas de Gradio que llamen al endpoint expuesto (usando el job ID y el token). No es necesario cambiar la configuración del servidor; la API y la autenticación se mantienen iguales.

¿HF Jobs o Inference Endpoints?

HF Jobs es la forma más rápida para montar un endpoint temporal, ideal para pruebas, evaluaciones y generación por lotes. Si buscan un servicio gestionado, listo para producción con mayor control, latencia garantizada y opciones de acceso público/fina granularidad, Inference Endpoints es la alternativa indicada. Elijan Jobs para prototipos ágiles y Endpoints para despliegues en producción.

Consejos finales para equipos en Latinoamérica

• Para POCs y pruebas de modelos locales, Jobs reduce la barrera de entrada: no necesitan invertir en servidores locales.
• Controlen costos: detengan los jobs cuando no los usen y seleccionen la flavor mínima viable.
• Seguridad y gobernanza: traten la URL del job y el token como credenciales sensibles; en entornos corporativos usen los controles de organización de HF.

Con estos pasos pueden tener un endpoint OpenAI‑compatible corriendo en minutos, consultar desde cualquier cliente compatible y escalar a modelos más grandes cuando lo requieran. Es una herramienta práctica para acelerar pruebas y evaluaciones sin complicarse con infraestructura.