¿Quieres probar un modelo localmente en la nube sin montar infraestructura compleja? Con HF Jobs y la imagen oficial de vLLM puedes levantar un servidor OpenAI-compatible con un solo comando, hacer pruebas, evaluaciones o generación por lotes, y luego cerrarlo cuando termines. ¿Suena bien? Vamos paso a paso.
Qué hace esto y para quién sirve
- Poner en marcha un servidor vLLM que responde como la API de OpenAI en minutos.
- Ideal para pruebas puntuales, evaluaciones, generación batch o para validar modelos antes de pasar a producción.
- No es lo mismo que un endpoint gestionado: si necesitas un servicio duradero y con scale-to-zero, entonces Inference Endpoints es la opción a considerar.
Requisitos rápidos
- Una forma de pago activa o saldo prepago positivo (Jobs se factura por tiempo de uso de hardware).
huggingface_hub >= 1.20.0.- Haber hecho login local:
pip install -U "huggingface_hub>=1.20.0"
hf auth login
- Mantén a mano un token HF con permisos de lectura para el namespace del job.
Comando mínimo: un solo comando para levantar el servidor
Este es el comando que hace todo el trabajo: pide GPU, expone el puerto y arranca vLLM.
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
Qué hace cada parte:
--flavor a10g-large: pide la máquina GPU. Cambia por la que necesites.--expose 8000: abre el puerto 8000 a través del proxy de Jobs.--timeout 2h: tiempo máximo de vida automático para el job.vllm/vllm-openai:latest: imagen que contiene vLLM con compatibilidad OpenAI.vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000: comando dentro del container que sirve el modelo.
El comando te devuelve un job_id y una URL como https://<job_id>--8000.hf.jobs que es donde responde la API.
Probar la API: curl y Python
vLLM habla la API de OpenAI y exige el token HF como bearer token. Ejemplo 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}
}'
Y desde Python, apuntando un cliente OpenAI al job:
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 llamar al endpoint, un chequeo rápido:
curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)"
Debería listar el modelo disponible.
Seguridad importante: el puerto expuesto está protegido. Cada petición debe llevar un token HF con acceso de lectura al namespace del job. No compartas la URL ni el token en lugares no confiables.
Parar el job y costos
Jobs se facturan por segundo. Cancela el job cuando termines:
hf jobs cancel <job_id>
El flag --timeout es una red de seguridad, pero cancelar manualmente es más barato. Por ejemplo, un a10g-large corre a 1.50 USD/hora; revisa hf jobs hardware para la lista de precios y elige la flavor más pequeña que funcione para tu modelo.
Escalar a modelos grandes y flags clave
Para modelos enormes debes seleccionar más GPUs y hacer sharding. Ejemplo para Qwen3.5-122B en 2x H200:
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
Puntos a entender:
--tensor-parallel-sizedebe coincidir con la cantidad de GPUs en la flavor (h200x2 -> 2, h200x8 -> 8).- Algunos modelos requieren limitar
--max-model-leny--max-num-seqspor memoria. Si ves errores de out-of-memory o cache-block, reduce esos valores primero. - Para modelos grandes, las flavors H200 suelen ofrecer mejor relación costo/beneficio.
Interfaz de chat con Gradio y razonamiento
Si prefieres una UI en vez de curl, un Gradio local puede apuntar al job. Añade --reasoning-parser deepseek_r1 al vllm serve para que la "razonamiento" venga en un campo separado, y ejecuta este snippet localmente:
import gradio as gr
from gradio import ChatMessage
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())
def chat(message, history):
messages = [{"role": m["role"], "content": m["content"]} for m in history if not m.get("metadata")]
messages.append({"role": "user", "content": message})
stream = client.chat.completions.create(model="Qwen/Qwen3-4B", messages=messages, stream=True)
thinking, answer = "", ""
for chunk in stream:
delta = chunk.choices[0].delta
thinking += delta.model_extra.get("reasoning", "")
answer += delta.content or ""
out = []
if thinking.strip():
status = "done" if answer.strip() else "pending"
out.append(ChatMessage(role="assistant", content=thinking, metadata={"title": "💭 Thinking", "status": status}))
if answer.strip():
out.append(ChatMessage(role="assistant", content=answer))
yield out
gr.ChatInterface(chat).launch()
Abre http://127.0.0.1:7860 y verás la ventana de chat con el razonamiento en un panel separable.
SSH, depuración y monitoreo GPU
Si necesitas entrar al container para ver nvidia-smi o logs en vivo, lanza el job con --ssh y asegúrate de tener tu llave pública registrada en huggingface.co/settings/keys:
hf jobs run --flavor a10g-large --expose 8000 --timeout 2h --ssh \
vllm/vllm-openai:latest \
vllm serve Qwen/Qwen3-4B --host 0.0.0.0 --port 8000
hf jobs ssh <job_id>
SSH hace la depuración y el monitoreo mucho más manejable que revisar logs remotos.
Integrar agentes (ejemplo: Pi) y tool calling
Si vas a usar agentes que llamen a herramientas, vLLM debe arrancarse con tool calling activado. Ejemplo para agentes con Pi y la familia Qwen3:
--enable-auto-tool-choice --tool-call-parser hermes
Luego registra el job como proveedor en ~/.pi/agent/models.json con la baseUrl apuntando a https://<job_id>--8000.hf.jobs/v1 y apiKey como !hf auth token. Lanza el agente y tendrás un agente Read/Write/Edit/Bash ejecutándose sobre tu modelo propio.
HF Jobs vs Inference Endpoints: cuándo elegir cada uno
- HF Jobs: máxima flexibilidad. Es como hacer
docker runen la nube de HF. Control total sobre la imagen, flags devllm serve, hardware y facturación por segundo. Ideal para experimentos, pruebas y cargas batch. - Inference Endpoints: solución gestionada para producción. Ofrecen control de acceso más fino, opciones de exposición pública o protegida, y scale-to-zero para ahorrar costos cuando no hay tráfico.
¿No estás seguro? Empieza con Jobs para validar y, si necesitas un servicio estable y duradero, migra a Endpoints.