단 한 번의 명령으로 HF Jobs에서 vLLM 서버 실행하기

테스트, 평가(evals), 또는 배치 생성(batch generation)을 위해 모델을 구축하는 가장 빠른 방법입니다. (만약 관리형의 프로덕션 준비 완료(production-ready) 서비스를 원하신다면, 그것은 Inference Endpoints를 위한 것입니다 — 마지막에 어떤 것을 선택할지에 대해 더 자세히 설명하겠습니다.)

다음은 전체 과정입니다.

• 결제 수단 또는 양(+)의 선불 크레딧 잔액 (Jobs는 하드웨어 사용량에 따라 분당 과금됩니다).
  huggingface_hub >= 1.20.0

:pip install -U "huggingface_hub>=1.20.0"

.- 로컬에 로그인됨:
hf auth login

.

hf jobs run은 HF 인프라를 위한 docker run입니다. 우리는 공식 vllm/vllm-openai 이미지를 사용하고, --flavor로 GPU를 요청하며, --expose로 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

--expose 8000은 HF의 공개 Jobs 프록시(public jobs proxy)를 통해 컨테이너의 포트를 라우팅합니다 (전체 참조를 보려면 Serve Models 가이드를 확인하세요). 이 명령은 서버에 접속 가능한 URL을 출력합니다:

✓ Job started
id: 6a381ca1953ed90bfb947332
url: https://huggingface.co/jobs/qgallouedec/6a381ca1953ed90bfb947332
...

6a381ca1953ed90bfb947332는 귀하의 Job ID입니다. 이를 계속 추적하세요, 나중에 필요합니다. 이 포스트의 나머지 부분에서는 이를 위한 자리 표시자(placeholder)로 <job_id>를 사용하겠습니다.

가중치(weights)를 다운로드하고 부팅하는 데 몇 분 정도 걸립니다. 로그에 Application startup complete가 표시되면, 서비스가 활성화된 것입니다.

vLLM은 OpenAI API를 지원하며, 모든 요청에는 Bearer 토큰으로서 귀하의 HF 토큰만 있으면 됩니다. 가장 빠르게 호출하는 방법은 curl입니다:

curl https://<job_id>--8000.hf.jobs/v1/chat/completions \
-H "Authorization: Bearer $(hf auth token)" \
-H "Content-Type: application/json" \
...

이 명령은 일반적인 OpenAI 스타일의 JSON을 반환하며, choices[0].message.content에 "Hello! How can I assist you today? 😊"가 담겨 있습니다.

또는, Python에서 OpenAI 클라이언트를 노출된 URL로 지정하고 토큰을 API 키로 전달하면 됩니다:

from huggingface_hub import get_token
from openai import OpenAI
client = OpenAI(
...

안녕하세요! 오늘 무엇을 도와드릴까요? 😊

시작하기 전 간단한 상태 확인: curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)"

위 명령어를 실행하면 모델 목록이 표시되어야 합니다.

🔐 엔드포인트(Endpoint)는 공개되지 않은 게이트형(gated) 방식입니다. 모든 요청은 해당 작업(job)의 네임스페이스(namespace)에 대한 읽기 권한(read access)을 가진 HF 토큰을 포함해야 합니다. 일반적인 브라우저 방문은 거부됩니다. 사실상 Jobs 프록시(proxy)가 귀하의 API 게이트 역할을 하며, 액세스 권한은 귀하(및 귀하의 조직)로 제한됩니다. 이는 개인적인 용도로는 적합하지만, URL을 다룰 때 주의가 필요합니다. URL이 공개될 것이라 예상하고 공유하지 마시고, 신뢰할 수 없는 곳에 토큰을 붙여넣지 마세요. 더 세밀한 권한 제어나 공개 액세스가 필요한 경우, 대신 적절한 게이트웨이(gateway)를 앞에 두십시오. 또는 아래의 HF Jobs 또는 Inference Endpoints를 참조하세요.

Jobs는 초 단위로 비용이 청구되므로, 작업이 끝나면 서버를 중지하십시오:

hf jobs cancel <job_id>

설정한 --timeout은 안전장치(자동 중지 기능)이지만, 명시적으로 취소하는 것이 더 저렴합니다. a10g-large는 시간당 $1.50에 실행됩니다. 전체 가격 목록을 확인하려면 hf jobs hardware를 실행하고, 모델에 적합한 가장 작은 사양(flavor)을 선택하세요.

동일한 명령어로 훨씬 더 큰 모델까지 확장할 수 있습니다. 더 강력한 --flavor를 선택하고, --tensor-parallel-size를 사용하여 vLLM이 GPU 전체에 모델을 샤딩(shard)하도록 설정하십시오. 예를 들어, 2× H200에서 실행되는 122B Qwen3.5 Mixture-of-Experts (MoE) 모델의 경우:

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
vllm/vllm-openai:latest \
vllm serve Qwen/Qwen3.5-122B-A10B \
...

--tensor-parallel-size는 flavor에 포함된 GPU 수와 일치해야 합니다 (h200x2 → 2, h200x8 → 8). 사용 가능한 사양을 확인하려면 hf jobs hardware를 실행하고, 큰 모델은 다운로드 및 로드 시간이 더 오래 걸리므로 더 긴 --timeout을 설정하십시오. 대규모 모델의 경우 H200 flavor가 일반적으로 가성비가 가장 좋습니다.

--max-model-len 32768 --max-num-seqs 256

다음 플래그(flags)는 이 모델에 특화된 것입니다: Qwen3.5-122B는 256K 토큰의 기본 컨텍스트(context)를 가진 하이브리드 Mamba/attention 아키텍처이며, 이는 vLLM의 기본 배치(batch) 설정에 사용할 메모리를 충분히 남겨두지 않습니다. 컨텍스트 길이(context length)와 동시 시퀀스 수(concurrent-sequence count)를 제한함으로써 GPU 메모리 내에 유지할 수 있습니다. 만약 모델이 메모리 부족(out-of-memory) 또는 캐시 블록(cache-block) 오류로 시작에 실패한다면, 이 두 값을 낮추는 것이 가장 먼저 시도해야 할 방법입니다. 그 외의 모든 것(공개된 URL, OpenAI 클라이언트, 토큰 인증)은 정확히 동일하게 유지됩니다.

curl 대신 채팅 창을 선호하시나요? 몇 줄의 Gradio 코드로 동일한 엔드포인트(endpoint)를 가리킬 수 있습니다. vllm serve 명령에 --reasoning-parser deepseek_r1을 추가하면 Qwen3의 사고 과정(thinking)이 별도의 필드로 반환됩니다(필수는 아니지만 유용합니다). 그 다음 이 코드를 로컬에서 실행하세요(job ID만 있으면 됩니다):

import gradio as gr
from gradio import ChatMessage
from huggingface_hub import get_token
...

실행 후 http://127.0.0.1:7860을 열고 채팅을 시작하세요. 사고 과정은 접이식 패널로 스트리밍되고, 답변은 그 아래에 나타납니다.

시작 실패를 디버깅하거나, GPU 메모리를 모니터링하거나, 로그를 대화형으로 확인(tail)해야 하나요? 실행 중인 작업(job)으로 직접 셸(shell)을 열 수 있습니다. --ssh를 사용하여 실행하고, 공개 키(public key)가 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

그 다음 job ID로 연결합니다:

hf jobs ssh <job_id>

이제 컨테이너 내부로 들어왔으며, 여기서 nvidia-smi를 실행하거나, 프로세스를 점검하거나, 모델을 직접 조작할 수 있습니다. 이는 외부에서 로그를 읽는 것보다 디버깅과 모니터링을 훨씬 쉽게 만들어 줍니다. SSH 지원을 위해서는 huggingface_hub >= 1.20.0 버전이 필요합니다.

동일한 엔드포인트로 터미널 코딩 에이전트(terminal coding agent)를 구동할 수도 있습니다. Pi는 프로바이더에 구애받지 않는(provider-agnostic) 에이전트 하네스(harness)입니다. 이를 해당 작업(job)으로 지정하면, 직접 호스팅한 모델 위에서 작동하는 Read/Write/Edit/Bash 에이전트를 얻을 수 있습니다.

먼저 설정해야 할 한 가지가 있습니다. 에이전트는 도구 호출 (tool calls)을 통해 모델을 구동하며, vLLM은 서버를 실행할 때 도구 호출 기능이 활성화되어 있어야만 이를 수락합니다. 따라서 --enable-auto-tool-choice와 모델 제품군에 맞는 --tool-call-parser를 사용하여 다시 실행하십시오 (Qwen3의 경우 hermes 사용).

에이전트는 더 강력한 모델을 사용할 때 이점이 있으므로, 이 단계에서 더 큰 모델을 도입하는 것이 좋습니다:

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
vllm/vllm-openai:latest \
vllm serve Qwen/Qwen3.5-122B-A10B \
...

그 다음, ~/.pi/agent/models.json에 해당 작업을 커스텀 프로바이더 (custom provider)로 추가합니다:

{
"providers": {
"hf-jobs": {
...

이제 해당 프로바이더를 대상으로 에이전트를 실행합니다:

pi

몇 줄 전의 명령어로 실행했던 모델이 이제 여러분의 터미널에서 대화형 코딩 에이전트를 구동하고 있습니다.

Hugging Face에서 모델을 서빙하는 방법이 HF Jobs만 있는 것은 아닙니다. Inference Endpoints는 동일한 목적을 위한 당사의 관리형 제품이며, 어떤 것이 적합한지는 여러분이 무엇을 추구하느냐에 따라 달라집니다.

최대의 유연성과 제어권을 원한다면 HF Jobs를 선택하십시오. 이는 HF 인프라 위에서 실행되는 단순한 docker run이므로, 사용자가 이미지, 정확한 vllm serve 플래그, 하드웨어를 직접 선택할 수 있으며 작업이 실행되는 동안 초 단위로 비용을 지불합니다. 따라서 실험, 일회성 평가 (evals), 배치 생성 (batch generation), 또는 무언가에 전념하기 전에 모델을 테스트해 보는 용도로 매우 적합합니다.

더 프로덕션 환경에 적합한(production-ready) 무언가를 원한다면 Inference Endpoints를 선택하십시오. 이 서비스는 장기 실행 서비스에 필요한 운영상의 편의 기능을 제공합니다. 더 세밀한 액세스 제어 (엔드포인트를 공개, 보호 또는 비공개로 설정 가능)와 사용하지 않는 동안 비용이 청구되지 않는 스케일 투 제로 (scale-to-zero) 기능이 포함되어 있습니다. 작업을 실행하는 것이 아니라 지속 가능한 엔드포인트를 구축하려는 경우라면 이것이 적합한 도구입니다.

이 포스트는 vLLM에 집중하고 있지만, 동일한 포트 노출 (expose-a-port) 패턴은 모든 OpenAI 호환 서버에서 작동합니다. llama.cpp로 GGUF를 서빙하거나 대신 SGLang을 실행하려면, 해당 백엔드들을 단계별로 안내하는 'Jobs에서 모델 서빙하기 (Serve Models on Jobs)' 가이드를 참조하십시오.