vLLM 0.21.0 서빙 가이드 — 모델 유형별 vllm serve 인자 정리

vLLM serving architecture (출처: blog.easecloud.io)

vLLM으로 모델을 서빙할 때 가장 먼저 마주치는 것이 vllm serve 명령어다. 인자가 많고 모델 유형에 따라 조합이 달라져서 처음엔 어디서부터 봐야 할지 막막하다. 이 글은 vLLM 0.21.0 기준으로 자주 쓰는 인자를 하나씩 풀고, 모델 유형별 서빙 예시를 정리한 것이다.

환경 준비

vLLM은 venv나 conda 환경에 설치해서 쓰는 것이 일반적이다. 서빙 전에 반드시 해당 환경을 활성화해야 한다.

source /path/to/venv/bin/activate

활성화하지 않으면 vllm 명령어를 찾지 못하거나 다른 버전이 실행될 수 있다.

vllm serve 기본 구조

vllm serve <모델 경로 또는 HuggingFace ID> [인자들...]

모델은 로컬 경로(/data/model/...)를 직접 지정하거나, HuggingFace 모델 ID(Qwen/Qwen3-8B)를 그대로 쓸 수 있다. 로컬 경로를 지정하면 네트워크 없이 서빙된다.

공통 인자 해설

모델 유형과 관계없이 거의 항상 등장하는 인자들이다.

--host / --port

--host 0.0.0.0 --port 10010

--host 0.0.0.0은 서버를 모든 네트워크 인터페이스에서 수신하도록 한다. 외부에서 접근해야 할 때 필요하다. 로컬 테스트만 할 거라면 127.0.0.1로도 충분하다.

--port는 서빙 포트 번호다. 여러 모델을 동시에 올릴 때는 포트를 다르게 지정해야 한다.

--tensor-parallel-size

--tensor-parallel-size 2

GPU 몇 장에 모델을 분산할지 지정한다. GPU가 2장이면 2, 4장이면 4를 넣으면 된다. 모델 크기가 단일 GPU VRAM을 초과하면 반드시 지정해야 한다.

--max-model-len

--max-model-len 131072

처리할 수 있는 최대 토큰 길이다. 모델이 지원하는 최대값 이하로 지정해야 하며, 높을수록 VRAM을 더 많이 사용한다. 실제 사용 패턴에 맞게 조정하면 메모리를 아낄 수 있다.

--gpu-memory-utilization

--gpu-memory-utilization 0.75

GPU VRAM의 몇 퍼센트를 vLLM이 사용할지 결정한다. 0에서 1 사이 값이며 기본값은 0.9다. 같은 GPU에 여러 모델을 올릴 때는 이 값을 낮춰 나눠 쓴다.

--served-model-name

--served-model-name Qwen3.5-27B

API 요청 시 모델 이름으로 쓸 별칭을 지정한다. 이 값을 지정하면 OpenAI 클라이언트에서 model="Qwen3.5-27B" 형태로 호출할 수 있다. 미지정 시 모델 경로가 그대로 이름이 된다.

모델 유형별 서빙 방법

1. 일반 LLM (Non-thinking)

Thinking 기능이 없거나 비활성화해서 쓸 때의 기본 형태다.

vllm serve /path/to/model \
  --host 0.0.0.0 \
  --port 10010 \
  --tensor-parallel-size 2 \
  --max-model-len 131072 \
  --gpu-memory-utilization 0.75 \
  --served-model-name my-model

추가 인자 없이 이 구성이 가장 기본이다.

2. Thinking / Reasoning 모델

Qwen3.5, QwQ 같은 thinking 기능이 있는 모델은 두 가지 모드로 서빙할 수 있다.

Thinking 활성화

vllm serve /path/to/Qwen3.5-27B \
  --host 0.0.0.0 \
  --port 10010 \
  --tensor-parallel-size 2 \
  --max-model-len 131072 \
  --gpu-memory-utilization 0.75 \
  --served-model-name Qwen3.5-27B \
  --reasoning-parser qwen3

--reasoning-parser qwen3 하나를 추가하면 thinking 출력을 파싱해서 별도 필드로 돌려준다.

Thinking 비활성화

vllm serve /path/to/Qwen3.5-27B \
  --host 0.0.0.0 \
  --port 10010 \
  --tensor-parallel-size 2 \
  --max-model-len 131072 \
  --gpu-memory-utilization 0.75 \
  --served-model-name Qwen3.5-27B \
  --default-chat-template-kwargs '{"enable_thinking": false}'

--default-chat-template-kwargs '{"enable_thinking": false}'를 추가하면 thinking 없이 일반 텍스트로만 응답한다. 빠른 응답이 필요하거나 thinking overhead가 불필요할 때 사용한다.

--reasoning-parser와 {"enable_thinking": false}를 동시에 쓰면, thinking은 기본적으로 비활성화되어 있되 API 요청 단위로 활성화할 수 있는 구성이 된다. 공식 가이드에서 권장하는 유연한 조합이다.

3. Embedding 모델

텍스트를 벡터로 변환하는 embedding 모델 서빙이다. LLM과 달리 생성 기능이 없으므로 생성 관련 인자가 필요 없다.

vllm serve /path/to/Qwen3-Embedding-8B \
  --host 0.0.0.0 \
  --port 10020 \
  --tensor-parallel-size 2 \
  --max-model-len 16384 \
  --gpu-memory-utilization 0.2

embedding 모델은 LLM 대비 VRAM 사용량이 작은 편이라 --gpu-memory-utilization을 낮게 잡아도 된다. 같은 서버에서 LLM과 함께 올릴 때 메모리 배분을 위해 이 값을 조정한다.

4. Tool Calling 활성화

function calling / tool use 기능을 쓰려면 두 인자가 필요하다.

vllm serve /path/to/Qwen3.5-27B \
  --host 0.0.0.0 \
  --port 10010 \
  --tensor-parallel-size 2 \
  --max-model-len 131072 \
  --gpu-memory-utilization 0.75 \
  --served-model-name Qwen3.5-27B \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder

--enable-auto-tool-choice: 모델이 자동으로 tool 사용 여부를 결정할 수 있게 한다.
--tool-call-parser qwen3_coder: 모델 출력에서 tool call 형식을 파싱하는 파서를 지정한다. 모델마다 파서가 다르며, Qwen3 계열은 qwen3_coder를 사용한다.

5. OCR / 멀티모달 모델

DeepSeek-OCR-2 같은 OCR 특화 모델은 일반 LLM과 다른 특수 인자가 필요하다.

vllm serve deepseek-ai/DeepSeek-OCR-2 \
  --host 0.0.0.0 \
  --port 8000 \
  --gpu-memory-utilization 0.1 \
  --max-model-len 8192 \
  --max-num-batched-tokens 8192 \
  --logits_processors vllm.model_executor.models.deepseek_ocr:NGramPerReqLogitsProcessor \
  --no-enable-prefix-caching \
  --mm-processor-cache-gb 0

일반 LLM과 다른 인자가 세 가지다.

--logits_processors: OCR 출력 품질을 높이기 위한 커스텀 로짓 프로세서를 지정한다. DeepSeek-OCR-2는 N-gram 기반 프로세서를 요구하며, 이 인자 없이 서빙하면 성능이 크게 떨어진다.
--no-enable-prefix-caching: prefix caching을 비활성화한다. OCR 작업은 매번 입력 이미지가 달라서 캐시 효율이 거의 없고 오히려 해싱 오버헤드만 생기므로 끄는 것이 낫다.
--mm-processor-cache-gb 0: 멀티모달 프로세서 캐시를 사용하지 않는다. 0으로 설정하면 캐시를 아예 쓰지 않는다.
--max-num-batched-tokens: 한 번에 배치로 처리할 수 있는 최대 토큰 수다. OCR 모델은 이미지를 토큰으로 변환하는 과정이 있어 이 값을 --max-model-len과 맞춰주는 것이 안전하다.

6. Guard / Safety 모델

Qwen3Guard-Gen 같은 안전성 분류 모델은 특별한 인자 없이도 서빙된다. 모델 자체가 작고 특화된 목적으로 쓰이기 때문이다.

vllm serve Qwen/Qwen3Guard-Gen-0.6B \
  --host 0.0.0.0 \
  --max-model-len 32768

ROCm(AMD GPU) 환경에서는 환경 변수를 추가로 설정해야 한다.

export VLLM_ROCM_USE_AITER=1

vllm serve Qwen/Qwen3Guard-Gen-0.6B \
  --host 0.0.0.0 \
  --max-model-len 32768

핵심 인자 한눈에 보기

인자	역할	예시 값
`--host`	수신 인터페이스	`0.0.0.0`
`--port`	포트 번호	`10010`
`--tensor-parallel-size`	GPU 분산 수	`2`, `4`, `8`
`--max-model-len`	최대 토큰 길이	`131072`
`--gpu-memory-utilization`	GPU VRAM 사용 비율	`0.75`
`--served-model-name`	API 호출용 모델 별칭	`my-model`
`--reasoning-parser`	Thinking 파서 활성화	`qwen3`
`--default-chat-template-kwargs`	Thinking 제어 등 템플릿 옵션	`'{"enable_thinking": false}'`
`--enable-auto-tool-choice`	Tool calling 자동 결정	(플래그)
`--tool-call-parser`	Tool call 파서 지정	`qwen3_coder`
`--logits_processors`	커스텀 로짓 프로세서	(클래스 경로)
`--no-enable-prefix-caching`	Prefix caching 비활성화	(플래그)
`--mm-processor-cache-gb`	멀티모달 캐시 크기(GB)	`0`
`--max-num-batched-tokens`	배치 처리 최대 토큰 수	`8192`

여러 모델을 동시에 서빙할 때

같은 서버에서 LLM과 embedding 모델을 함께 올리는 것이 실무에서 흔한 구성이다. 포트를 다르게 잡고 --gpu-memory-utilization을 적절히 나눠야 한다.

# 터미널 1 — LLM
vllm serve /path/to/Qwen3.5-27B \
  --port 10010 \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.75 \
  --served-model-name Qwen3.5-27B \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder

# 터미널 2 — Embedding
vllm serve /path/to/Qwen3-Embedding-8B \
  --port 10020 \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.2 \
  --max-model-len 16384

두 프로세스가 같은 GPU를 공유하므로 두 --gpu-memory-utilization 합이 1.0을 넘지 않도록 계획해야 한다.