vLLM으로 Hugging Face 모델 로컬 서빙하는 방법: 설치부터 API 호출까지
vLLM을 사용해 Hugging Face Hub의 모델을 내 PC나 서버에서 바로 API 형태로 띄우는 과정을 블로그용으로 정리했습니다. 가장 쉬운 기본 명령어부터 Hugging Face 로그인, 로컬 폴더 서빙, Docker 대안, 자주 쓰는 옵션, 자주 생기는 오류까지 한 번에 볼 수 있게 구성했습니다.
핵심 요약
- vLLM은 OpenAI 호환 서버를 제공하므로 기존 OpenAI 클라이언트를 거의 그대로 붙일 수 있습니다.
- 가장 쉬운 시작은
uv로 가상환경을 만들고uv pip install vllm --torch-backend=auto를 실행하는 방식입니다. - 기본 서빙은
vllm serve <허깅페이스 모델 ID>한 줄로 시작합니다. - private 또는 gated 모델은
hf auth login또는HF_TOKEN설정이 먼저 필요합니다. - 채팅 모델인데
/v1/chat/completions가 실패하면 chat template부터 확인해야 합니다.
http://localhost:8000 입니다.
--max-model-len, --gpu-memory-utilization, --cpu-offload-gb 조합을 먼저 조정합니다.
--trust-remote-code나 로컬 폴더 경로 방식으로 확장합니다.
왜 vLLM으로 시작하면 좋은가
vLLM은 LLM 추론과 서빙에 초점을 맞춘 오픈소스 도구입니다. 공식 README에서도 Hugging Face 모델과의 매끄러운 통합, OpenAI 호환 API 서버, 그리고 다양한 하드웨어 지원을 핵심 장점으로 설명합니다. 블로그 관점에서는 “허깅페이스 모델을 빠르게 로컬 API로 바꾸는 도구”라고 이해하면 가장 쉽습니다.
기존 OpenAI 클라이언트 재활용
서버를 띄운 뒤 base_url만 로컬 주소로 바꾸면 OpenAI Python 클라이언트나 OpenAI 호환 클라이언트를 그대로 붙이기 쉽습니다.
모델 ID 한 줄 실행
가장 기본적인 흐름은 vllm serve Qwen/Qwen2.5-1.5B-Instruct처럼 모델 ID 하나로 시작됩니다.
서빙 옵션이 풍부함
포트 변경, API 키 적용, GPU 메모리 사용률 조정, 컨텍스트 길이 축소, CPU 오프로드, 텐서 병렬화까지 CLI 옵션으로 손쉽게 조절할 수 있습니다.
복사해서 바로 쓰는 가장 빠른 시작
“일단 내 컴퓨터에서 Hugging Face 모델을 API 서버로 띄워보고 싶다”면 아래 순서만 따라가면 됩니다.
기본 주소는 http://localhost:8000이고, 서버는 한 번에 모델 하나를 호스팅합니다.
uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
# private/gated 모델이 아니라면 이 단계는 건너뛰어도 됨
hf auth login
# 기본 서빙
vllm serve Qwen/Qwen2.5-1.5B-Instruct --host 0.0.0.0 --port 8000
# 서버 확인
curl http://localhost:8000/v1/models
# 채팅 요청 테스트
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen2.5-1.5B-Instruct",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "vLLM이 뭐야?"}
]
}'
vLLM으로 Hugging Face 모델을 로컬 서빙하는 단계별 사용법
아래 순서대로 진행하면 설치부터 실제 호출까지 한 번에 끝낼 수 있습니다. 실무에서는 1~5단계만 익혀도 대부분의 초기 프로토타입을 바로 만들 수 있습니다.
환경 준비
vLLM Quickstart는 빠른 시작 기준으로 Linux와 Python 3.10~3.13을 안내합니다. 가장 무난한 경로는 NVIDIA GPU가 있는 Linux 환경입니다. 메모리 여유가 없다면 처음부터 너무 큰 모델을 고르지 않는 것이 좋습니다.
가상환경 생성 후 vLLM 설치
공식 Quickstart는 uv 사용을 권장합니다. --torch-backend=auto를 사용하면 설치 시점에 적절한 PyTorch 인덱스를 자동으로 고르는 흐름이 제공됩니다.
uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
conda 환경을 이미 쓰고 있다면 conda로 Python 환경을 만들고, 그 안에서 uv를 설치해 같은 방식으로 진행할 수도 있습니다.
허깅페이스 로그인 또는 토큰 준비
public 모델은 바로 동작하는 경우가 많지만, private 또는 gated 저장소는 토큰이 필요합니다.
Hugging Face 문서에서는 User Access Token을 권장하며, 읽기 전용이면 read 권한 토큰으로 충분한 경우가 많습니다.
hf auth login
CLI 로그인에 성공하면 토큰이 로컬에 저장되고, Hugging Face 라이브러리들이 이 토큰을 재사용할 수 있습니다. 환경 변수로 직접 넣고 싶다면 다음처럼 설정해도 됩니다.
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
모델 ID로 서버 실행
가장 기본적인 형태는 아래 한 줄입니다. 모델이 캐시에 없으면 Hugging Face Hub에서 내려받고, 이미 캐시에 있으면 재사용합니다.
vllm serve Qwen/Qwen2.5-1.5B-Instruct
포트와 호스트를 명시하고 싶다면 다음처럼 실행하면 됩니다.
vllm serve Qwen/Qwen2.5-1.5B-Instruct \
--host 0.0.0.0 \
--port 8000
서버는 한 번에 모델 하나를 호스팅합니다. 같은 장비에서 여러 모델을 띄우려면 포트와 자원 분배 전략을 따로 잡아야 합니다.
서버 정상 동작 확인
먼저 모델 목록 엔드포인트가 열리는지 확인하세요. 가장 단순한 헬스체크 역할을 합니다.
curl http://localhost:8000/v1/models
그다음 채팅 API를 호출하면 실제 추론까지 바로 검증할 수 있습니다.
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen2.5-1.5B-Instruct",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "한국어로 자기소개해줘."}
]
}'
OpenAI Python 클라이언트로 붙이기
vLLM 서버는 OpenAI 호환 API를 제공하므로, 클라이언트 코드에서는 base_url만 로컬 주소로 바꾸면 되는 경우가 많습니다.
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="EMPTY", # 서버에 --api-key를 걸지 않았다면 임시 문자열로도 충분
)
response = client.chat.completions.create(
model="Qwen/Qwen2.5-1.5B-Instruct",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "vLLM의 장점을 3줄로 설명해줘."}
],
)
print(response.choices[0].message.content)
OpenAI에 없는 vLLM 전용 파라미터가 필요하면 extra_body에 넣는 방식도 사용할 수 있습니다.
response = client.chat.completions.create(
model="Qwen/Qwen2.5-1.5B-Instruct",
messages=[{"role": "user", "content": "안녕"}],
extra_body={"top_k": 50},
)
Hugging Face InferenceClient로도 호출 가능
Hugging Face 문서에도 InferenceClient가 vLLM 같은 로컬 OpenAI 호환 엔드포인트를 호출할 수 있다고 안내되어 있습니다. 이미 Hugging Face SDK를 많이 쓰고 있다면 이 방식도 꽤 편합니다.
from huggingface_hub import InferenceClient
client = InferenceClient(model="http://localhost:8000")
response = client.chat.completions.create(
messages=[
{"role": "user", "content": "서울과 부산의 차이를 간단히 설명해줘."}
],
max_tokens=200,
)
print(response.choices[0].message.content)
private·gated 모델, 커스텀 모델, 최신 모델 처리
vLLM은 Hugging Face Hub의 모델 ID를 직접 받을 수 있고, 토큰이 필요한 경우 HF_TOKEN을 사용합니다.
또한 Supported Models 문서에는 Transformers modeling backend를 통해 호환되는 새 모델을 더 넓게 다룰 수 있다고 설명합니다.
# 예: trust_remote_code가 필요한 모델이라면
vllm serve some-org/some-model --trust-remote-code
아직 vLLM 네이티브 구현이 없어도 Transformers backend와 호환된다면 동작 가능성이 있습니다. 단, 이런 경우에는 먼저 문서의 supported models / custom models 안내를 확인하는 편이 안전합니다.
실전에서 자주 쓰는 vLLM 옵션
기본 명령어만으로도 서버는 뜨지만, 실제로는 아래 옵션들을 자주 함께 씁니다. 특히 메모리 문제, 모델 식별명, 보안, 다운로드 위치 관련 옵션은 사용 빈도가 높습니다.
| 옵션 | 언제 쓰나 | 예시 |
|---|---|---|
--host, --port |
외부 장비에서 접근하거나 포트를 바꾸고 싶을 때 | --host 0.0.0.0 --port 8000 |
--api-key 또는 VLLM_API_KEY |
로컬망 또는 팀 환경에서 최소한의 접근 제어를 둘 때 | --api-key my-secret-key |
--tensor-parallel-size |
한 노드 내 여러 GPU에 모델을 나눠 올릴 때 | -tp 2 |
--gpu-memory-utilization |
동일 GPU에서 다른 작업과 메모리를 나눠 써야 할 때 | --gpu-memory-utilization 0.7 |
--max-model-len |
긴 컨텍스트 때문에 메모리 부족이 날 때 | --max-model-len 8k |
--cpu-offload-gb |
VRAM이 부족하지만 CPU 메모리로 조금 버틸 수 있을 때 | --cpu-offload-gb 10 |
--download-dir |
모델 다운로드와 로딩 위치를 별도 디렉터리로 고정하고 싶을 때 | --download-dir /data/hf-cache |
--revision |
브랜치, 태그, 커밋 기준으로 모델 버전을 고정하고 싶을 때 | --revision main |
--served-model-name |
API 응답에서 모델명을 더 짧거나 일관되게 보이게 하고 싶을 때 | --served-model-name qwen-local |
--chat-template |
채팅 모델인데 tokenizer에 chat template이 없을 때 | --chat-template ./chat_template.jinja |
--generation-config vllm |
모델 저장소의 generation_config.json 대신 vLLM 기본값을 쓰고 싶을 때 | --generation-config vllm |
--trust-remote-code |
커스텀 구현을 포함한 호환 모델을 로드해야 할 때 | --trust-remote-code |
서버가 안 뜨는 가장 흔한 이유는 메모리 부족입니다. 우선순위는 보통
더 작은 모델 선택 → max_model_len 축소 → gpu_memory_utilization 조정 → cpu_offload_gb 사용 순서가 실용적입니다.
vLLM은 기본적으로 Hugging Face 저장소의 generation_config.json을 적용할 수 있습니다.
샘플링 결과가 예상과 다르면 이 설정이 먼저 개입했는지 확인해보세요.
모델을 미리 내려받아 로컬 폴더에서 서빙하는 방법
회사 내부망, 느린 네트워크, 배포 반복, 캐시 제어가 중요한 환경이라면 모델을 미리 받아 두는 방식이 편합니다.
Hugging Face CLI의 hf download는 전체 저장소 다운로드와 --local-dir 옵션을 지원합니다.
# 전체 모델 저장소를 특정 폴더로 미리 다운로드
hf download Qwen/Qwen2.5-1.5B-Instruct --local-dir ./models/qwen2.5-1.5b-instruct
# 로컬 폴더 경로를 그대로 서빙
vllm serve ./models/qwen2.5-1.5b-instruct
vLLM 문서에도 모델 인자로 Hugging Face 모델 ID뿐 아니라 기존 로컬 경로를 직접 넣을 수 있다고 설명되어 있습니다.
캐시 디렉터리를 전역으로 바꾸고 싶다면 Hugging Face의 HF_HUB_CACHE 환경 변수나 vLLM의 --download-dir를 함께 고려하면 됩니다.
- 빌드 서버와 실행 서버를 분리할 때
- 오프라인 또는 느린 인터넷 환경에서 반복 배포할 때
- 동일 모델을 자주 재시작하면서 캐시 위치를 관리하고 싶을 때
- 로컬 폴더에는 최소한
config.json등 올바른 구조가 있어야 합니다. - 커스텀 모델이면
--trust-remote-code와 호환성 문서 확인이 필요할 수 있습니다. - 다운로드한 revision을 고정 관리하면 재현성이 좋아집니다.
Docker로 띄우는 방법
로컬 Python 환경을 건드리고 싶지 않거나 팀 내부에서 동일한 실행 이미지를 공유하려면 공식 Docker 이미지를 쓰는 편이 깔끔합니다.
vLLM은 vllm/vllm-openai 이미지를 공식 제공하며, Hugging Face 캐시와 HF_TOKEN 전달 예시도 문서에 포함되어 있습니다.
docker run --runtime nvidia --gpus all \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--env "HF_TOKEN=$HF_TOKEN" \
-p 8000:8000 \
--ipc=host \
vllm/vllm-openai:latest \
--model Qwen/Qwen3-0.6B
Docker 방식을 쓰더라도 기본 개념은 같습니다. 모델 ID를 넘기고, 8000 포트를 열고, 필요하면 토큰을 전달합니다. 추가 CLI 옵션은 이미지 이름 뒤에 이어 붙이면 됩니다.
vLLM Docker 문서에는
--ipc=host 또는 충분한 --shm-size가 필요하다고 적혀 있습니다.
텐서 병렬이나 프로세스 간 데이터 공유에서 특히 중요합니다.
자주 생기는 문제와 해결 포인트
아래 항목만 알아도 시행착오를 많이 줄일 수 있습니다. 초기에 가장 자주 막히는 곳은 토큰, 메모리, chat template, generation_config 네 가지입니다.
모델 다운로드가 실패한다
private 또는 gated 저장소일 수 있습니다. hf auth login으로 로그인하거나 HF_TOKEN을 설정했는지 확인하세요.
서버가 뜨자마자 OOM이 난다
더 작은 모델로 바꾸고, --max-model-len을 줄이고, 필요하면 --gpu-memory-utilization이나 --cpu-offload-gb를 조정하세요.
chat/completions만 실패한다
모델의 tokenizer 설정에 chat template이 없을 가능성이 큽니다. --chat-template으로 직접 지정해보세요.
기본 생성 결과가 예상과 다르다
Hugging Face 저장소의 generation_config.json이 적용되고 있을 수 있습니다. vLLM 기본값만 쓰려면 --generation-config vllm을 사용하세요.
새 모델이라 supported list에 안 보인다
Transformers modeling backend로 동작 가능한지 확인하세요. 호환 모델이라면 --trust-remote-code 또는 로컬 경로 방식으로 여전히 시도해볼 수 있습니다.
같은 모델명으로 응답받고 싶지 않다
외부 애플리케이션과 이름을 맞추고 싶다면 --served-model-name으로 API 응답상의 모델명을 별도로 지정하세요.
- Hugging Face 토큰이 필요한 모델인지 먼저 확인했는가
- 작은 Instruct 모델로 구동 검증을 먼저 했는가
/v1/models응답이 정상인지 확인했는가- 채팅 모델에 chat template이 있는가
- 메모리 부족이면
max_model_len과cpu_offload_gb를 조정했는가 - 결과 차이가 크면
generation_config영향을 확인했는가
FAQ
검색 유입이 많이 붙는 질문 위주로 정리했습니다. 블로그 본문 아래 FAQ 섹션으로 붙여도 자연스럽게 쓰일 수 있도록 문장을 구성했습니다.
vLLM은 어떤 도구인가요?
vLLM은 LLM 추론과 서빙에 특화된 오픈소스 도구입니다. OpenAI 호환 API 서버를 제공해 Hugging Face 모델을 로컬에서 API 형태로 띄우기 좋습니다.
아무 Hugging Face 모델이나 바로 서빙할 수 있나요?
무조건은 아닙니다. 가장 먼저 vLLM의 supported models 문서를 확인하는 것이 안전합니다. 다만 vLLM은 Transformers modeling backend도 지원해서, 호환되는 모델이라면 네이티브 구현이 없어도 동작할 수 있습니다.
비공개 모델이나 gated 모델도 가능한가요?
가능합니다. Hugging Face 토큰으로 로그인하거나 HF_TOKEN을 설정하면 됩니다. private 또는 gated 저장소 접근에는 토큰이 필요합니다.
chat/completions가 에러 나는 이유는 뭔가요?
대부분은 모델 토크나이저에 chat template이 없기 때문입니다. 이런 경우 --chat-template 옵션으로 템플릿을 직접 지정해야 합니다.
기본 샘플링 결과가 기대와 다를 때는 어떻게 하나요?
vLLM은 기본적으로 모델 저장소의 generation_config.json을 적용할 수 있습니다. vLLM 기본값으로만 쓰고 싶다면 --generation-config vllm 옵션을 붙이면 됩니다.
모델을 미리 받아서 로컬 폴더에서 서빙할 수 있나요?
가능합니다. hf download로 로컬 폴더에 미리 내려받은 뒤, vllm serve <폴더경로> 형태로 실행할 수 있습니다.
SEO 최적화 블로그 제목 추천
검색 키워드인 vLLM, Hugging Face, 로컬 서빙, OpenAI 호환, API 서버를 중심으로 제목을 뽑았습니다. 기술 블로그형 제목과 실무형 제목을 섞어두었으니 매체 톤에 맞춰 고르면 됩니다.
- vLLM으로 Hugging Face 모델 로컬 서빙하는 방법: 설치부터 API 호출까지
- vLLM 사용법 총정리: 허깅페이스 모델을 로컬 서버로 띄우는 방법
- Hugging Face 모델을 vLLM으로 서빙하는 법: OpenAI API 호환 서버 만들기
- vLLM 로컬 서버 구축 가이드: Hugging Face 모델 배포와 테스트 방법
- vLLM + Hugging Face 튜토리얼: 로컬 LLM 서빙 빠르게 시작하기
- Qwen·Llama 모델을 vLLM으로 로컬 배포하는 방법
- vLLM 설치 및 서빙 가이드: 허깅페이스 모델 API 서버 만들기
- OpenAI 호환 로컬 LLM 서버 만들기: vLLM으로 Hugging Face 모델 띄우기
- vLLM Docker 사용법: Hugging Face 모델을 로컬에서 서빙하는 방법
- 허깅페이스 모델 로컬 추론 서버 구축: vLLM 실전 가이드
vLLM으로 Hugging Face 모델을 로컬에서 서빙하는 방법을 단계별로 정리했습니다.
설치, HF 로그인, vllm serve, curl/OpenAI 호출, Docker, 자주 쓰는 옵션, 문제 해결, SEO 제목까지 한 번에 확인하세요.
vllm-huggingface-local-serving-guide
공식 참고 자료
본 문서는 vLLM 공식 문서와 Hugging Face 공식 문서를 바탕으로 정리했습니다. 블로그 발행 전 최신 옵션이나 지원 범위를 재확인하려면 아래 링크부터 보는 것이 가장 안전합니다.
'AI' 카테고리의 다른 글
| QuiverAI 사용법 총정리: 텍스트·이미지로 SVG 로고와 일러스트 만드는 방법 (0) | 2026.04.06 |
|---|---|
| Variant AI 사용법 총정리: 웹·앱 UI 아이디어를 빠르게 만드는 방법 (0) | 2026.04.06 |
| 클로드 코드(Claude Code) 활용법 30가지: 실무 적용 사례 총정리 (0) | 2026.04.06 |
| Paperclip 완전 가이드: 설치부터 Docker·API·어댑터·운영 전략까지 한눈에 보는 paperclipai/paperclip (0) | 2026.03.31 |
| OpenClaw 플러그인 추천 10선: 생산성·보안·메모리 확장까지 실전 가이드 (1) | 2026.03.18 |