Jobs에서 모델 서빙하기

Jobs에서 모델 서빙하기

노출된 포트(exposed ports)를 사용하면 Job이 임시 추론 서버로 동작할 수 있어요. GPU flavor에서 vLLM을 시작하고, OpenAI 호환 클라이언트를 Job의 URL에 연결하고, 끝나면 Job을 취소하면 되죠. Job이 실행되는 동안에만 분당으로 비용을 지불하고, 엔드포인트는 Job과 함께 사라져요.

출처: 문서

본문

노출된 포트(exposed ports)를 사용하면 Job이 임시 추론 서버로 동작할 수 있어요: GPU flavor에서 vLLM을 시작하고, OpenAI 호환 클라이언트를 Job의 URL에 연결하고, 작업이 끝나면 Job을 취소하면 돼요. Job이 실행되는 동안 분당으로 비용을 지불하며, 엔드포인트는 Job과 함께 사라져요.

이는 엔드포인트가 제품 자체라기보다 수단일 때 잘 맞아요: 평가 실행, 데이터 라벨링 세션, 뜨거운 모델에 대한 프롬프트 반복, 또는 오후 동안만 존재하면 되는 데모 같은 경우요.

[!TIP] 사라지지 않는 더 영구적인 엔드포인트를 원한다면 Inference Endpoints를 원하는 거예요 — 오토스케일링, 모니터링, 안정적인 URL을 제공하는 관리형 인프라예요.

vLLM 서버 시작하기

vllm/vllm-openai 이미지에는 모든 것이 미리 설치돼 있어요. 한 명령으로 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은 Hugging Face 토큰을 비밀로 Job에 전달해서 모델 다운로드가 인증되게 해요 — gated나 프라이빗 모델에 필요하며, 다른 모든 것에도 더 높은 rate limit과 빠른 다운로드를 줘요.

[!NOTE] Jobs는 제공한 명령을 직접 실행해요 — docker run처럼 이미지의 entrypoint에 인자를 전달하지 않아요. 항상 전체 명령(--model ...가 아니라 vllm serve ...)을 명시해 주세요.

서버가 준비되기까지 몇 분 걸려요 (이미지 pull, 모델 다운로드, 모델 로드). hf jobs logs -f <job_id>로 진행 상황을 따라가고, 로그에 Application startup complete가 보이면 서버가 준비된 거예요.

클라이언트 연결

노출된 포트는 Job의 네임스페이스에 대한 read 접근 권한이 있는 HF 토큰을 Bearer 토큰으로 요구해요. OpenAI 호환 서버라면 이게 클라이언트의 API 키로 바로 들어가요 — base URL은 노출된 포트 URL에 /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는 추론(reasoning) 모델이라 응답은 최종 답변 앞의 thinking 태그 안에 추론을 포함해요.

또는 curl로:

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

토큰이 Authorization 헤더에 실려 가기 때문에 이 URL은 스크립트, 노트북, 에이전트 — OpenAI 호환 API를 쓰는 어디서든 동작해요. 브라우저에서 직접 열 수는 없어요.

llama.cpp로 GGUF 모델 서빙하기

같은 패턴이 HTTP를 말하는 어떤 서버에도 동작해요. llama.cpp의 llama serve는 -hf 플래그로 GGUF 파일을 Hub에서 직접 가져와 같은 OpenAI 호환 API를 서빙해요. 예를 들어 Gemma 4 E4B를 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

--는 Job의 명령을 hf jobs run의 자체 옵션과 구분해요 — llama serve의 플래그가 CLI 자체에 파싱되는 걸 막아야 하기 때문이에요.

[!TIP] 모델 저장소를 읽기 전용 볼륨으로 마운트하고 서버를 파일에 직접 지정하면 모델 다운로드를 통째로 건너뛸 수 있어요:

>>> 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

다운로드할 게 없어서 서버가 훨씬 빨리 시작돼요 — 로드되면서 마운트된 저장소에서 모델이 스트리밍돼요.

[!WARNING] 서버는 0.0.0.0에서 리슨해야 해요. llama serve는 기본적으로 127.0.0.1에 바인딩하는데, jobs 프록시가 여기에 닿지 못해요 — --host 0.0.0.0을 명시적으로 전달해 주세요.

같은 원칙이 다른 OpenAI 호환 서버(SGLang 등)에도 적용돼요: 노출된 포트에서 서버를 시작하고, 0.0.0.0에서 리슨하고, HF 토큰을 API 키로 연결하세요.

서버 중지

Job — 그리고 청구 — 은 취소하거나 타임아웃에 도달하면 중지돼요(기본 30분; 더 긴 세션은 --timeout을 명시해 설정):

>>> hf jobs cancel <job_id>

[!NOTE] 노출된 포트는 huggingface_hub >= 1.19.0이 필요하며 Job의 하드웨어 가격 위에 별도로 청구돼요 — Jobs 가격을 참고해요.

더 알아보기 (Learn more)

  • --expose 포트의 OpenAI 호환 서버는 base URL에 /v1을 붙이고 HF 토큰을 API 키로 쓰면 바로 연결돼요.
  • 서버는 반드시 --host 0.0.0.0에서 리슨해야 jobs 프록시가 닿을 수 있어요.