Jobs에서 모델 서빙

노출된 포트를 사용하면 Job을 임시 추론 서버로 사용할 수 있습니다. GPU flavor에서 vLLM을 시작하고, OpenAI 호환 클라이언트를 Job의 URL로 지정한 뒤, 작업이 끝나면 Job을 취소하면 됩니다. Job이 실행되는 동안 분당 과금이 적용되며, Job이 종료되면 엔드포인트도 함께 사라집니다.

엔드포인트가 최종 산출물이 아니라 수단으로 사용되는 경우, 즉 평가 실행, 데이터 라벨링 세션, 핫 모델에 대한 프롬프트 반복 개선, 오후 동안만 유지되면 되는 데모와 같은 상황에서 이 방식이 적합합니다.

영구적으로 유지되는 엔드포인트가 필요하시다면, 오토스케일링, 모니터링, 안정적인 URL을 갖춘 관리형 인프라를 제공하는 Inference Endpoints를 사용하세요.

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 토큰을 시크릿으로 작업을 통해 전달하여 모델 다운로드를 인증합니다. 게이트드 또는 비공개 모델에는 필수적이며, 기타 모든 모델의 경우 더 높은 레이트 리밋과 더 빠른 다운로드를 제공합니다.

Jobs는 사용자가 제공한 명령을 직접 실행하며, docker run처럼 이미지의 entrypoint에 인수를 전달하지 않습니다. 항상 전체 명령을 명시적으로 작성해야 합니다(vllm serve ...처럼, --model ...만 작성하는 것이 아닙니다).

서버가 준비되려면 몇 분 정도 걸립니다(이미지 풀, 모델 다운로드, 모델 로드). hf jobs logs -f <job_id>를 사용하여 진행 상황을 추적할 수 있으며, 로그에 Application startup complete가 표시되면 서버가 준비된 것입니다.

클라이언트 연결

노출된 포트는 작업의 namespace에 대한 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는 추론 모델이므로, 최종 답변 전에 <think> 태그 안에 추론 과정을 포함하여 응답을 반환합니다.

또는 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!"}]}'

토큰이 Authorization 헤더를 통해 전송되므로, OpenAI 호환 API를 사용하는 모든 환경에서 스크립트, 노트북, 에이전트 등으로부터 이러한 URL을 사용할 수 있습니다. 브라우저에서 직접 열 수 없습니다. HF 토큰 없이 포트를 제공하려면 --expose-public을 사용하세요. 포트 노출을 참조하세요.

llama.cpp로 GGUF 모델 서빙

HTTP를 지원하는 모든 서버에서 동일한 패턴이 작동합니다. llama.cpp의 llama serve는 -hf 플래그를 사용하여 Hub에서 GGUF 파일을 직접 가져와 동일한 OpenAI 호환 API를 제공합니다. 예를 들어, Gemma의 권장 샘플링 설정으로 Gemma 4 E4B를 서빙하려면:

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

--는 작업의 명령을 hf jobs run의 자체 옵션과 구분하는 역할을 합니다. llama serve의 플래그가 CLI 자체에 의해 파싱되지 않도록 하기 위해 여기서는 필요합니다.

모델 저장소를 읽기 전용 볼륨으로 마운트하고 서버를 해당 파일로 직접 지정하면 모델 다운로드를 완전히 생략할 수 있습니다:

복사됨

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

다운로드할 것이 없으므로 서버가 훨씬 더 빠르게 시작됩니다. 모델은 로딩되는 동안 마운트된 저장소에서 스트리밍됩니다.

서버는 0.0.0.0에서 리스닝해야 합니다. llama serve는 기본적으로 127.0.0.1에 바인딩되며, 이는 jobs proxy가 도달할 수 없습니다. --host 0.0.0.0을 명시적으로 전달하세요.

다른 OpenAI 호환 서버(SGLang, …)에도 동일한 방식이 적용됩니다: 서버를 노출된 포트에서 시작하고, 0.0.0.0에서 리스닝하며, HF 토큰을 API 키로 사용하여 연결합니다.

서버를 중지합니다

작업 — 그리고 그에 대한 과금 — 은 작업을 취소하거나 타임아웃(기본값 30분; 더 긴 세션의 경우 --timeout을 명시적으로 설정)에 도달하면 중단됩니다:

>>> hf jobs cancel <job_id>

노출된 포트는 huggingface_hub >= 1.19.0이 필요하며, 작업의 하드웨어 가격에 추가 과금됩니다. Jobs 가격을 참조하세요.