hf jobs run을 이용한 vLLM 서버 배포
GPU 서버를 대여하고 도커(Docker) 환경을 설정해 LLM 추론 서버를 띄우는 과정은 매번 반복되는 번거로운 인프라 구축 작업이다. 허깅페이스 잡스(HF Jobs)는 `hf jobs run` 명령어 한 줄로 vLLM 서버를 즉시 배포하고 OpenAI 호환 API 형태로 사용할 수 있는 환경을 제공한다. 이를 통해 인프라 설정 시간을 줄이고 모델 테스트와 평가에 집중할 수 있다.
`hf jobs run`은 허깅페이스 인프라에서 도커 컨테이너를 실행하는 명령어다. 서버 구축을 위해 vLLM의 공식 이미지인 `vllm/vllm-openai`를 사용하며, `--flavor` 옵션으로 GPU 사양을 지정한다. flavor는 GPU 종류와 메모리 크기 등 하드웨어 구성을 의미하며, `hf jobs hardware` 명령어로 사용 가능한 목록을 확인할 수 있다. 명령어를 입력하면 시스템이 모델 가중치를 다운로드하고 부팅하며, 로그에 `Application startup complete` 문구가 나타나면 서버가 활성화된다.
외부 접속을 위해 `--expose 8000` 옵션을 사용하면 컨테이너의 8000번 포트가 허깅페이스 공용 잡스 프록시(Public Jobs Proxy)로 라우팅된다. 명령어를 실행하면 서버에 접속할 수 있는 고유 URL이 출력된다. vLLM은 OpenAI API 규격을 따르므로, 출력된 주소를 통해 기존 OpenAI 라이브러리를 그대로 사용하여 모델에 요청을 보낼 수 있다.
비용은 사용한 시간만큼 초 단위로 과금된다. a10g-large 사양 기준 시간당 1.50달러가 청구된다. 사용자는 모델 크기에 맞는 가장 작은 flavor를 선택해 비용을 최적화할 수 있다. 배포를 위한 전체 명령어는 다음과 같다.
hf jobs run --flavor a10g-large --expose 8000 vllm/vllm-openaiOpenAI 호환 API 연결과 SSH 디버깅 구조
허깅페이스 잡스는 플랫폼 토큰 하나로 인증 미들웨어와 게이트웨이 설정을 통합한다. 배포된 vLLM 서버는 OpenAI API 규격을 따르며, 모든 요청 헤더에 허깅페이스 토큰을 Bearer 토큰으로 포함해 전송한다.
bash
curl https://<job_id>--8000.hf.jobs/v1/chat/completions -H "Authorization: Bearer $(hf auth token)" -d '{"model": "...", "messages": [{"role": "user", "content": "Hello!"}]}'
파이썬 환경에서는 OpenAI 클라이언트의 `base_url`을 배포된 서버 주소로 지정하고 API 키 자리에 허깅페이스 토큰을 입력해 연결한다.
client = OpenAI(base_url="https://<job_id>--8000.hf.jobs/v1", api_key=hf_token)서버 상태 확인을 위한 헬스 체크는 `v1/models` 엔드포인트에 요청을 보내 현재 로드된 모델 목록을 출력하는 방식으로 수행한다.
curl https://<job_id>--8000.hf.jobs/v1/models -H "Authorization: Bearer $(hf auth token)"잡스 프록시가 API 게이트웨이 역할을 수행해 사용자나 조직 단위로 접근 권한을 제한한다. 공개되지 않은 게이트드 엔드포인트 방식이므로 반드시 읽기 권한이 있는 토큰을 지참해야 접속 가능하다.
서버 실행 시 `--ssh` 옵션을 추가하면 컨테이너 내부로 직접 쉘 접속이 가능하다. 이 기능을 사용하려면 huggingface.co/settings/keys 페이지에 공개키를 등록해야 한다.
hf jobs ssh <job_id>접속 후 `nvidia-smi` 명령어를 실행해 GPU 메모리 점유율을 실시간으로 모니터링할 수 있다. 이는 로그 파일만으로는 확인하기 어려운 메모리 누수나 프로세스 상태를 즉각적으로 진단하게 한다. 해당 SSH 기능은 `huggingface_hub` 라이브러리 버전 1.20.0 이상에서 지원되며, 모델 로딩 실패나 런타임 오류 발생 시 쉘에서 직접 프로세스를 검사해 디버깅 사이클을 단축한다.
HF Jobs와 Inference Endpoints의 선택 기준
배포된 서버를 실제 서비스에 적용할 때는 HF Jobs와 Inference Endpoints 중 목적에 맞는 도구를 선택해야 한다. 두 서비스 모두 허깅페이스 인프라를 기반으로 하지만 제어 방식과 운영 목적에서 차이가 있다.
HF Jobs는 도커 컨테이너를 실행하는 방식으로, 사용자가 컨테이너 이미지와 vLLM 플래그를 완전히 제어한다. 유연한 제어가 필요한 일회성 작업에 최적화되어 있으며, 하드웨어 사양과 `vLLM serve` 세부 옵션을 직접 입력해 환경을 구축한다. 비용이 초 단위로 정밀하게 과금되므로 모델 성능 확인 실험, 특정 데이터셋에 대한 배치 생성, 정식 도입 전 평가 단계에 적합하다.
반면 안정적인 운영이 필요한 장기 서비스에는 관리형 서비스인 Inference Endpoints가 적합하다. 엔드포인트 성격에 따라 공개, 보호, 비공개 중 하나를 선택해 접근 권한을 엄격하게 관리할 수 있다. 또한 요청이 없을 때 컴퓨팅 자원을 0으로 줄이는 Scale-to-zero 기능을 지원해 비활성 상태의 과금을 자동으로 중단한다.
결국 선택 기준은 제어권의 범위와 운영 목적이다. 도커 기반의 완전한 제어와 초 단위 비용 지불이 중요하다면 HF Jobs를, 정교한 권한 관리와 자동화된 비용 최적화가 필요한 프로덕션 환경이라면 Inference Endpoints를 선택한다.
Qwen3.5-122B 등 대규모 모델 최적화 및 확장
Qwen3.5-122B 같은 초거대 모델은 메모리 용량 확보와 더불어 효율적인 배치 전략이 필수적이다. 이 모델은 맘바(Mamba)와 어텐션(Attention)이 결합된 하이브리드 구조이며, 기본 컨텍스트가 256K로 길어 vLLM 기본 설정 사용 시 GPU 메모리를 모두 점유하는 OOM(Out of Memory) 오류가 발생한다.
초거대 모델을 안정적으로 서빙하려면 `--tensor-parallel-size` 옵션으로 모델 가중치를 GPU 개수에 맞춰 분할 배치하는 분산 처리 방식이 필요하다. 예를 들어 `h200x2` 사양 서버에서 이 값을 2로 설정하면 두 개의 GPU가 연산을 병렬로 처리한다. H200 flavor는 일반 GPU보다 높은 메모리 대역폭을 제공해 성능 대비 비용 효율이 높다.
또한 메모리 점유율을 제어하는 최적화 플래그를 적용해야 한다. Qwen3.5-122B의 경우 `--max-model-len`을 32768로 제한하고, 최대 요청 수인 `--max-num-seqs`를 256으로 설정해 GPU 메모리 범위를 유지한다. 기본 설정 사용 시 vLLM이 가용 메모리보다 많은 KV 캐시(Key-Value Cache) 공간을 요구해 서버가 중단될 수 있으므로, 캐시 블록 오류 발생 시 이 두 수치를 하향 조정해야 한다.
hf jobs run --flavor h200x2 --expose 8000 vllm/vllm-openai --tensor-parallel-size 2 --max-model-len 32768 --max-num-seqs 256코딩 에이전트 구현을 위한 도구 호출 설정
vLLM 서버에서 `--enable-auto-tool-choice` 옵션을 추가하면 모델이 스스로 도구 사용 여부를 결정하는 도구 호출 기능을 활성화할 수 있다. 모델 제품군에 맞는 출력 형식을 해석하기 위해 `--tool-call-parser` 옵션으로 파서를 지정하며, Qwen3 모델은 `hermes`를 사용한다.
hf jobs run --flavor h200x2 --expose 8000 vllm/vllm-openai --enable-auto-tool-choice --tool-call-parser hermes이 설정은 모델이 단순 텍스트 응답을 넘어 외부 함수 실행 명령을 내릴 수 있게 한다. 에이전트 환경에서는 복잡한 추론 능력이 요구되므로 `h200x2` 같은 고사양 GPU를 지정해 큰 모델을 구동하는 것이 유리하다.
구축한 vLLM 서버를 에이전트 하네스인 Pi에 연결하려면 `~/.pi/agent/models.json` 설정 파일에 커스텀 프로바이더로 등록해야 한다. 이 파일을 통해 에이전트는 요청을 보낼 엔드포인트와 모델 식별자를 인식한다.
설정 완료 후 `pi agent run` 명령어를 입력하면 터미널 기반의 자율 코딩 에이전트가 구동된다.
pi agent run이 환경에서 에이전트는 파일 읽기, 쓰기, 수정 및 배시(Bash) 실행 권한을 가진다. 모델이 도구 호출을 요청하면 Pi 하네스가 이를 가로채 실제 시스템 명령어로 실행하고 그 결과를 다시 모델에게 전달한다.
GPU 서버 대여와 도커 설정 같은 반복적인 인프라 구축 작업은 모델 실험의 속도를 늦추는 물리적 병목이었다. `hf jobs run` 명령어로 vLLM 서버를 즉시 배포하고 OpenAI 호환 API로 연결하는 방식은 인프라 설계 시간을 제거하고 모델 검증 단계로 바로 진입하게 만든다.
인프라 구축 시간을 없애고 사용한 초 단위로만 비용을 지불하는 환경은 실험의 효율성을 결정하는 핵심 기준이 된다. 본문에서 다룬 `hf jobs run` 명령어로 최적의 하드웨어 조합을 찾는 실험을 시작하는 것이 인프라 오버헤드를 제거하고 개발 속도를 높이는 가장 빠른 방법이다.
