HF Jobs에서 vLLM 서버를 한 명령으로 실행하기

HF Jobs에서 vLLM 서버를 한 명령으로 실행하기

이 글은 Hugging Face 블로그의 Run a vLLM Server on HF Jobs in One Command를 한국어로 번역한 글입니다.

HF Jobs에서 vLLM 서버를 한 명령으로 실행하기

단일 명령으로 개인용 OpenAI-호환 LLM 엔드포인트를 허깅페이스 인프라에서 시작할 수 있습니다 — 프로비저닝할 서버도 없고, 쿠버네티스도 필요 없으며, 초당 요금으로 지불합니다. 일단 실행되면 노트북이나 다른 기기에서, 또는 어디서든 이를 쿼리할 수 있습니다.

테스트, 평가 또는 배치 생성에 모델을 가장 빠르게 배치하는 방법입니다. (대신 관리형의 프로덕션 준비가 된 서비스를 원하신다면, 그것이 바로 Inference Endpoints이며 — 끝에 more on when to pick which가 있습니다.)

다음은 처음부터 끝까지의 전체 흐름입니다.

전제 조건

결제 수단 또는 양의 선불 크레딧 잔액(Jobs는 하드웨어 사용량에 따라 분 단위로 청구됩니다).
huggingface_hub >= 1.20.0: pip install -U "huggingface_hub>=1.20.0".
로컬로 로그인됨: hf auth login.

서버 시작하기

hf jobs run은 허깅페이스 인프라를 위한 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은 컨테이너의 포트를 허깅페이스의 공개 Jobs 프록시를 통해 라우팅합니다(전체 참조는 Serve Models guide를 참조하십시오). 명령은 서버에 접근 가능한 URL을 출력합니다:

✓ Job started
  id: 6a381ca1953ed90bfb947332
  url: https://huggingface.co/jobs/qgallouedec/6a381ca1953ed90bfb947332
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a381ca1953ed90bfb947332--8000.hf.jobs

6a381ca1953ed90bfb947332은 당신의 작업 ID입니다. 이를 추적해 두세요, 나중에 필요합니다. 이 글의 나머지 부분에서 <job_id>을 그것의 자리 표시자로 사용할 예정입니다.

가중치를 다운로드하고 부팅하는 데 몇 분 정도 기다리세요. 로그에 Application startup complete가 표시되면 라이브 상태입니다.

어디에서나 쿼리하기

vLLM은 OpenAI API를 사용하며, 모든 요청은 베어러 토큰으로 허깅페이스 토큰이 필요합니다. 이를 호출하는 가장 빠른 방법은 curl입니다:

curl https://<job_id>--8000.hf.jobs/v1/chat/completions \
  -H "Authorization: Bearer $(hf auth token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-4B",
    "messages": [{"role": "user", "content": "Hello!"}],
    "chat_template_kwargs": {"enable_thinking": false}
  }'

일반적인 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(
    base_url="https://<job_id>--8000.hf.jobs/v1",
    api_key=get_token(),
)
resp = client.chat.completions.create(
    model="Qwen/Qwen3-4B",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)
print(resp.choices[0].message.content)

Hello! How can I assist you today? 😊

시작하기 전 빠른 상태 점검: curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)"에 모델이 나열되어 있어야 합니다.

[!경고] 🔐 엔드포인트는 게이트되어 공개되지 않습니다. 모든 요청은 작업의 네임스페이스에 대한 읽기 권한이 있는 허깅페이스 토큰이 필요합니다. 일반 브라우저 방문은 거부됩니다. 사실상 작업 프록시는 API 게이트 역할을 하며, 접근은 귀하(및 귀하의 조직)에게 한정됩니다. 개인 사용에는 괜찮지만 URL을 다룰 때는 공개로 여길 것을 기대하지 말고 토큰을 신뢰할 수 없는 곳에 붙여넣지 마십시오. 더 세밀하거나 공개 접근이 필요하면 대신 적절한 게이트웨이를 앞에 두십시오. 아래의 HF Jobs or Inference Endpoints?를 참조하십시오.

정리하기

Jobs는 초당 과금되므로 작업이 끝나면 서버를 중지하세요:

hf jobs cancel <job_id>

설정한 --timeout은 안전망이며(자동 중지 기능이 있습니다). 그러나 명시적으로 취소하는 것이 더 저렴합니다. a10g-large은 시간당 $1.50에 실행되며 전체 가격표는 hf jobs hardware에서 확인하고 모델에 맞는 가장 작은 플래버를 선택하세요.

더 나아가기: 더 큰 모델들

같은 명령으로 훨씬 큰 모델들로 확장할 수 있습니다 — 더 강력한 --flavor를 선택하고, --tensor-parallel-size로 모델을 GPU에 걸쳐 샤딩하도록 vLLM에 지시하세요. 예를 들어, 2× H200에서의 122B Qwen3.5 mixture-of-experts 모델:

hf jobs run --flavor h200x2 --expose 8000 --timeout 2h \
  vllm/vllm-openai:latest \
  vllm serve Qwen/Qwen3.5-122B-A10B \
  --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 \
  --max-model-len 32768 --max-num-seqs 256

--tensor-parallel-size는 해당 플레이버의 GPU 수와 일치해야 합니다 (h200x2 → 2, h200x8 → 8). hf jobs hardware를 실행하여 이용 가능 항목을 확인하고, 더 큰 모델에는 더 긴 --timeout를 부여하세요. 다운로드 및 로드에 시간이 더 걸리기 때문입니다. 대형 모델의 경우 H200 플레이버가 보통 가장 가치 있습니다.

--max-model-len 32768 --max-num-seqs 256 플래그는 이 모델에만 해당합니다: Qwen3.5-122B는 기본 컨텍스트가 256K 토큰인 하이브리드 맘바/어텐션 아키텍처로, vLLM의 기본 배치 설정에 충분한 메모리를 남기지 못합니다. 컨텍스트 길이와 동시 시퀀스 수를 제한하면 GPU의 메모리 내에 머물 수 있습니다. 메모리 부족(out-of-memory) 또는 캐시 차단(cache-block) 오류로 시작하지 못하는 경우, 이 두 값을 먼저 낮추는 것이 가장 먼저 시도하는 방법입니다. 나머지 모든 것은(노출된 URL, OpenAI 클라이언트, 토큰 인증)은 정확히 동일하게 유지됩니다.

더 나아가기: UI로 채팅하기

curl보다 채팅 창을 선호하십니까? Gradio의 몇 줄이 같은 엔드포인트를 가리킵니다. --reasoning-parser deepseek_r1을 vllm serve 명령에 추가하여 Qwen3의 사고를 별도의 필드로 되돌려 받도록 하세요(필수는 아니지만 도움이 됩니다). 그런 다음 이 코드를 로컬에서 실행합니다(필요한 것은 작업 ID뿐입니다):

import gradio as gr
from gradio import ChatMessage
from huggingface_hub import get_token
from openai import OpenAI

client = OpenAI(base_url="https://<job_id>--8000.hf.jobs/v1", api_key=get_token())

def chat(message, history):
    messages = [{"role": m["role"], "content": m["content"]} for m in history if not m.get("metadata")]
    messages.append({"role": "user", "content": message})
    stream = client.chat.completions.create(model="Qwen/Qwen3-4B", messages=messages, stream=True)

    thinking, answer = "", ""
    for chunk in stream:
        delta = chunk.choices[0].delta
        thinking += delta.model_extra.get("reasoning", "")
        answer += delta.content or ""
        out = []
        if thinking.strip():
            status = "done" if answer.strip() else "pending"
            out.append(ChatMessage(role="assistant", content=thinking, metadata={"title": "💭 Thinking", "status": status}))
        if answer.strip():
            out.append(ChatMessage(role="assistant", content=answer))
        yield out

gr.ChatInterface(chat).launch()

실행하고 http://127.0.0.1:7860를 열어 채팅하면 — 추론이 접이식 패널에 흐르고, 아래에 정답이 나타납니다.

더 나아가기: 실행 중인 서버에 SSH로 접속하기

시작 실패를 디버깅하거나, GPU 메모리를 모니터링하거나, 로그를 대화형으로 tail하려면? 실행 중인 작업에 바로 셸을 열 수 있습니다. --ssh로 시작하고 공개 키가 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

그런 다음 작업 ID로 연결합니다:

hf jobs ssh <job_id>

이제 컨테이너 내부에 들어와 nvidia-smi를 실행하고, 프로세스를 점검하거나 모델을 직접 확인할 수 있습니다 — 외부에서 로그를 읽는 것보다 디버깅과 모니터링이 훨씬 쉽습니다. SSH 지원은 huggingface_hub >= 1.20.0가 필요합니다.

더 나아가기: Pi를 사용한 코딩 에이전트 백엔드로 사용하기

같은 엔드포인트가 터미널 코딩 에이전트를 백엔드로 사용할 수 있습니다. Pi은 공급자 독립적인 에이전트 하니스입니다. 작업을 가리키도록 설정하면, 자체 호스팅 모델에서 Read/Write/Edit/Bash 에이전트가 실행됩니다.

먼저 설정해야 할 한 가지: 에이전트는 도구 호출을 통해 모델을 구동하며, 서버가 도구 호출 활성화 상태로 시작된 경우에만 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 \
  --host 0.0.0.0 --port 8000 --tensor-parallel-size 2 \
  --max-model-len 32768 --max-num-seqs 256 \
  --reasoning-parser deepseek_r1 \
  --enable-auto-tool-choice --tool-call-parser hermes

그런 다음 ~/.pi/agent/models.json에 작업을 커스텀 프로바이더로 추가합니다:

{
  "providers": {
    "hf-jobs": {
      "baseUrl": "https://<job_id>--8000.hf.jobs/v1",
      "api": "openai-completions",
      "apiKey": "!hf auth token",
      "models": [
        { "id": "Qwen/Qwen3.5-122B-A10B" }
      ]
    }
  }
}

그 에이전트를 그것에 대해 시작합니다:

pi

몇 개의 명령 앞에 시작한 모델이 이제 터미널에서 대화형 코딩 에이전트를 구동하고 있습니다.

HF Jobs 또는 Inference Endpoints?

허깅페이스에서 모델을 서비스하는 유일한 방법은 HF Jobs가 아닙니다. Inference Endpoints은 같은 작업에 대한 관리형 제품이며, 어느 쪽이 적합한지는 사용 목적에 따라 다릅니다.

최대의 유연성과 제어를 원할 때는 HF Jobs를 선택하세요: 허깅페이스 인프라에서 docker run에 해당하며, 이미지, 정확한 vllm serve 플래그, 하드웨어를 선택하고 작업이 실행되는 동안 초당 요금을 지불합니다. 이는 실험, 단발성 평가, 배치 생성, 또는 어떤 것을 확정하기 전에 모델을 시험해보기에 아주 잘 맞습니다.

좀 더 프로덕션에 가까운 것을 원하신다면 Inference Endpoints를 선택하세요. 이들은 장기 실행되는 서비스에 필요한 운영상의 편의 기능을 제공합니다: 더 세밀한 접근 제어(엔드포인트가 공개, 보호, 또는 비공개일 수 있음)와 제로 스케일링으로 비활성 상태에서도 과금되지 않습니다. 지속 가능한 엔드포인트를 구축하려면 이것이 필요한 도구입니다.

추가 읽기

이 포스트는 vLLM에 집중하지만, 포트를 노출하는 동일한 패턴은 어떤 OpenAI-호환 서버에서도 작동합니다. llama.cpp로 GGUF를 서비스하거나 대신 SGLang을 실행하려면, Serve Models on Jobs guide를 참조하세요. 이 백엔드들을 차례로 설명합니다.

26 Jun 2026