Servir modelos en Jobs

Con puertos expuestos, un Job puede actuar como un servidor de inferencia temporal: inicia vLLM en un sabor de GPU, apunta cualquier cliente compatible con OpenAI a la URL del job y cancela el job cuando termines. Pagas por minuto mientras el job se ejecuta y el punto de acceso desaparece con el job.

Es una buena opción cuando el punto de acceso es un medio y no el producto en sí: una ejecución de evaluación, una sesión de etiquetado de datos, iterar sobre prompts contra un modelo caliente, o una demostración que solo necesita estar activa durante una tarde.

Si deseas un punto de acceso más permanente que no desaparezca, lo que necesitas son los Inference Endpoints, que proporcionan infraestructura administrada con escalado automático, monitoreo y URLs estables.

Iniciar un servidor de vLLM

La imagen vllm/vllm-openai tiene todo preinstalado. Un solo comando inicia un servidor compatible con OpenAI:

>>> hf jobs run --detach --expose 8000 --flavor a10g-small -s HF_TOKEN \
...   vllm/vllm-openai \
...   vllm serve LiquidAI/LFM2.5-8B-A1B --max-model-len 8192
✓ Job started
  id: 6a2b137a59bbdade52d4a58c
  url: https://huggingface.co/jobs/davanstrien/6a2b137a59bbdade52d4a58c
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a2b137a59bbdade52d4a58c--8000.hf.jobs

-s HF_TOKEN transfiere tu token de Hugging Face al trabajo como un secreto, de modo que la descarga del modelo esté autenticada: es obligatorio para modelos con acceso restringido o privados, y te otorga límites de tasa más altos y descargas más rápidas para todo lo demás.

Jobs ejecuta directamente el comando que proporcionas; no pasa argumentos al entrypoint de la imagen como lo hace docker run. Escribe siempre el comando completo (vllm serve ..., no solo --model ...).

El servidor tarda unos minutos en estar listo (descarga de la imagen, descarga del modelo, carga del modelo). Siga el progreso con hf jobs logs -f <job_id>; el servidor estará listo cuando los registros muestren Application startup complete.

Conectar un cliente

Los puertos expuestos requieren un token de HF con acceso read al espacio de nombres del trabajo, pasado como token Bearer. Para un servidor compatible con OpenAI, esto se inserta directamente como clave de API del cliente: la URL base es la URL del puerto expuesto más /v1:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://6a2b137a59bbdade52d4a58c--8000.hf.jobs/v1",
    api_key=os.environ["HF_TOKEN"],  # any token with read access to the job's namespace
)

response = client.chat.completions.create(
    model="LiquidAI/LFM2.5-8B-A1B",
    messages=[{"role": "user", "content": "Write a haiku about ephemeral compute."}],
)
print(response.choices[0].message.content)

LFM2.5 es un modelo de razonamiento, por lo que la respuesta incluye su razonamiento dentro de las etiquetas <think> antes de la respuesta final.

O con curl:

>>> curl https://6a2b137a59bbdade52d4a58c--8000.hf.jobs/v1/chat/completions \
...   -H "Authorization: Bearer $HF_TOKEN" \
...   -H "Content-Type: application/json" \
...   -d '{"model": "LiquidAI/LFM2.5-8B-A1B", "messages": [{"role": "user", "content": "Hello!"}]}'

Dado que el token viaja en la cabecera Authorization, estas URLs funcionan desde scripts, notebooks y agentes, es decir, en cualquier lugar donde se utilice una API compatible con OpenAI. No se pueden abrir directamente en un navegador. Para servir un puerto sin un token de HF, usa --expose-public; consulta Expose Ports.

Sirve modelos GGUF con llama.cpp

El mismo patrón funciona con cualquier servidor que hable HTTP. llama serve de llama.cpp obtiene los archivos GGUF directamente del Hub con la bandera -hf y sirve la misma API compatible con OpenAI. Por ejemplo, para servir Gemma 4 E4B con los ajustes de muestreo recomendados por Gemma:

>>> hf jobs run --detach --expose 8080 --flavor a10g-small -s HF_TOKEN \
...   ghcr.io/ggml-org/llama.cpp:server-cuda -- \
...   /app/llama serve -hf ggml-org/gemma-4-E4B-it-GGUF \
...   --host 0.0.0.0 --port 8080 -ngl 99 \
...   --temp 1.0 --top-p 0.95 --top-k 64

El -- separa el comando del trabajo de las propias opciones de hf jobs run; es necesario aquí porque, de lo contrario, las banderas de llama serve serían analizadas por la propia CLI.

Puede omitir por completo la descarga del modelo montando el repositorio del modelo como un volumen de solo lectura y apuntando el servidor directamente al archivo:

Copiado

>>> hf jobs run --detach --expose 8080 --flavor a10g-small -s HF_TOKEN \
...   -v hf://ggml-org/gemma-4-E4B-it-GGUF:/model:ro \
...   ghcr.io/ggml-org/llama.cpp:server-cuda -- \
...   /app/llama serve --model /model/gemma-4-E4B-it-Q4_K_M.gguf \
...   --host 0.0.0.0 --port 8080 -ngl 99

El servidor se inicia mucho más rápido porque no hay nada que descargar: el modelo se transmite desde el repositorio montado a medida que se carga.

Tu servidor debe escuchar en 0.0.0.0. llama serve se une a 127.0.0.1 de forma predeterminada, lo que el proxy de trabajos no puede alcanzar; pasa --host 0.0.0.0 explícitamente.

Lo mismo aplica a cualquier otro servidor compatible con OpenAI (SGLang, …): inicia el servidor en un puerto expuesto, escucha en 0.0.0.0 y conéctate con tu token de HF como clave de API.

Detener el servidor

El trabajo —y su facturación— se detiene cuando lo cancelas o cuando se alcanza su tiempo de espera (30 minutos por defecto; establece --timeout explícitamente para sesiones más largas):

>>> hf jobs cancel <job_id>

Los puertos expuestos requieren huggingface_hub >= 1.19.0 y se facturan además del precio del hardware del trabajo; consulte Jobs pricing.