Hugging Face Jobs: 단일 명령으로 vLLM 서버 배포하기

Hugging Face Jobs: 단일 명령으로 vLLM 서버 배포하기

Hugging Face는 단일 명령으로 Hugging Face 인프라에서 vLLM을 사용하여 비공개 OpenAI 호환 LLM 엔드포인트를 시작하는 방법을 도입했습니다. 이 접근 방식은 수동 서버 프로비저닝이나 Kubernetes 관리가 필요 없으며, 빠른 테스트, 평가 및 배치 생성에 적합한 초당 과금 모델을 제공합니다.

HF Jobs를 통한 vLLM 서버 배포

사용자는 hf jobs run 명령을 사용하여 vLLM 서버를 시작할 수 있으며, 이는 Hugging Face 인프라에서 docker run과 유사하게 작동합니다. 공식 vllm/vllm-openai 이미지를 사용하고 --flavor 플래그로 하드웨어를 지정하면, 사용자는 Hugging Face jobs 프록시를 통해 서버를 공개 인터넷에 노출할 수 있습니다.

예시 실행 명령:

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 프록시를 통해 컨테이너의 포트를 라우팅합니다.
  • --flavor: GPU 하드웨어를 지정합니다(예: a10g-large).
  • --timeout: 지정된 기간後に 작업을 자동으로 중지하는 안전망을 설정합니다.

시작되면 시스템은 고유한 job ID와 접근 가능한 URL(예: https://<job_id>--8000.hf.jobs)을 제공합니다.

쿼리 및 인증

vLLM은 OpenAI API를 구현하므로, 배포된 엔드포인트는 표준 OpenAI 클라이언트 또는 curl을 사용하여 쿼리할 수 있습니다. 모든 요청은 인증을 위해 Hugging Face 토큰을 bearer 토큰으로 포함해야 합니다.

인증 요구 사항:

  • 엔드포인트는 게이트되어 있으며 공개되지 않습니다.
  • 요청은 job의 네임스페이스에 대한 읽기 권한이 있는 HF 토큰이 필요합니다.
  • 접근은 사용자 또는 해당 조직에 한정됩니다.

대형 모델 확장

HF Jobs는 더 강력한 하드웨어 플레버와 vLLM의 텐서 병렬성을 결합하여 더 큰 모델로 확장할 수 있습니다. 예를 들어, 두 개의 H200 GPU에 Qwen3.5-122B-A10B와 같은 122B 파라미터 모델을 배포하려면 모델을 GPU 간에 샤딩하기 위해 --tensor-parallel-size 2 플래그가 필요합니다.

매우 큰 모델의 경우 메모리 관리가 중요합니다. 소스에 따르면, 모델이 OOM(메모리 부족) 또는 캐시 블록 오류로 시작에 실패하는 경우 컨텍스트 길이(--max-model-len)와 동시 시퀀스 수(--max-num-seqs)를 제한하는 것이 주요 해결책입니다.

고급 운영 기능

SSH를 통한 인터랙티브 디버깅

사용자는 실행 중인 작업에 --ssh 플래그를 추가하여 직접 셸을 열 수 있습니다.これにより、nvidia-smi와 같은 도구를 사용한 실시간 모니터링 및 인터랙티브 로그 검사가 가능해집니다.

hf jobs ssh <job_id>

코딩 에이전트와의 통합

배포된 vLLM 서버는 Pi와 같은 터미널 코딩 에이전트의 백엔드로 사용할 수 있습니다. 이를 활성화하려면 --enable-auto-tool-choice를 통해 툴 호출을 활성화하고 특정 --tool-call-parser(예: Qwen3 모델의 경우 hermes)로 서버를 시작해야 합니다.

HF Jobs vs. Inference Endpoints

Hugging Face는 필요한 제어 및 안정성 수준에 따라 모델을 제공하는 두 가지 주요 방법을 제공합니다:

특징 HF Jobs Inference Endpoints
주요 사용 사례 실험, 일회성 평가, 배치 생성 프로덕션 준비 완료, 오래 지속되는 서비스
제어 최대 유연성(이미지, 플래그, 하드웨어 선택) 관리된 운영 경험
청구 작업 기간에 따른 초당 과금 스케일 투 제로(비활성 시 과금 없음)
액세스 제어 HF 토큰/네임스페이스를 통한 게이트 세분화됨(공개, 보호됨 또는 비공개)

사용 전제 조건

HF Jobs를 사용하여 vLLM을 배포하려면 사용자가 다음이 필요합니다:

  • 결제 수단 또는 양의 선불 크레딧 잔액.
  • huggingface_hub >= 1.20.0이 pip를 통해 설치됨.
  • hf auth login을 통한 로컬 인증

Sources