Servir Modelos em Jobs

Com portas expostas, um Job pode atuar como um servidor de inferência temporário: inicie o vLLM em um sabor de GPU, aponte qualquer cliente compatível com a OpenAI para a URL do job e cancele o job quando terminar. Você paga por minuto enquanto o job está em execução, e o endpoint desaparece junto com o job.

Essa é uma boa opção quando o endpoint é um meio e não o produto em si: uma execução de avaliação, uma sessão de rotulagem de dados, a iteração de prompts contra um modelo quente, ou uma demonstração que precisa existir apenas por uma tarde.

Se você deseja um endpoint mais permanente que não desaparecerá, você quer Inference Endpoints, que fornece infraestrutura gerenciada com autoscaling, monitoramento e URLs estáveis.

Iniciar um servidor vLLM

A imagem vllm/vllm-openai tem tudo pré-instalado. Um comando inicia um servidor compatível com a 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 encaminha seu token do Hugging Face para o job como um segredo, de modo que o download do modelo seja autenticado — necessário para modelos com acesso restrito ou privados, e que proporciona limites de taxa mais altos e downloads mais rápidos para todos os demais.

Jobs executa diretamente o comando que você fornece — ele não passa argumentos para o entrypoint da imagem, como o docker run faz. Sempre especifique o comando completo (vllm serve ..., e não apenas --model ...).

O servidor leva alguns minutos para ficar pronto (pull da imagem, download do modelo, carregamento do modelo). Acompanhe o progresso com hf jobs logs -f <job_id>; o servidor está pronto quando os logs exibirem Application startup complete.

Conectar um cliente

Portas expostas exigem um token do HF com acesso read ao namespace do job, passado como um token Bearer. Para um servidor compatível com a OpenAI, isso se encaixa diretamente na chave de API do cliente — a URL base é a URL da porta exposta mais /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 é um modelo de raciocínio, portanto a resposta inclui seu raciocínio dentro das tags <think> antes da resposta final.

Ou com 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!"}]}'

Como o token viaja no cabeçalho Authorization, essas URLs funcionam em scripts, notebooks e agentes — em qualquer lugar em que você usaria uma API compatível com a OpenAI. Elas não podem ser abertas diretamente em um navegador. Para servir uma porta sem um token do HF, use --expose-public — veja Expose Ports.

Sirva modelos GGUF com llama.cpp

O mesmo padrão funciona com qualquer servidor que utilize HTTP. O llama serve do llama.cpp busca arquivos GGUF diretamente do Hub com a flag -hf e oferece a mesma API compatível com a OpenAI. Por exemplo, para servir o Gemma 4 E4B com as configurações de amostragem recomendadas pela 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

O -- separa o comando do job das próprias opções de hf jobs run — necessário aqui porque as flags de llama serve seriam analisadas pelo próprio CLI caso contrário.

Você pode pular completamente o download do modelo montando o repositório do modelo como um volume somente de leitura e apontando o servidor diretamente para o arquivo:

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

O servidor inicia muito mais rápido, pois não há nada para baixar — o modelo é transmitido do repositório montado conforme é carregado.

Seu servidor deve escutar em 0.0.0.0. O llama serve se vincula a 127.0.0.1 por padrão, o que o proxy de jobs não consegue alcançar — passe --host 0.0.0.0 explicitamente.

O mesmo se aplica a qualquer outro servidor compatível com a OpenAI (SGLang, …): inicie o servidor em uma porta exposta, escute em 0.0.0.0 e conecte-se com seu token da HF como chave de API.

Pare o servidor

O trabalho — e sua cobrança — é interrompido quando você o cancela ou quando o tempo limite é atingido (30 minutos por padrão; defina --timeout explicitamente para sessões mais longas):

>>> hf jobs cancel <job_id>

Portas expostas exigem huggingface_hub >= 1.19.0 e são cobradas em adição ao preço do hardware do job — veja Preços de Jobs.