vLLM 로컬 서버 설정: 작은 모델부터 0.30 적응형 검증까지

여러 사람이 동시에 질문하면 vLLM은 진행 중인 요청을 묶어 GPU에서 계산해요. 이 방식을 continuous batching이라고 해요. 서버 전체가 1초에 생성한 토큰을 합산하면 처리량을 알 수 있고, 내 질문 한 건의 첫 토큰과 완료 시간을 재면 개인이 느끼는 응답 속도를 알 수 있어요.

동시 사용자가 늘면 전체 완료량이 증가해도 한 요청은 큐에서 기다릴 수 있고 각 요청의 KV cache⁶도 메모리를 써요. 동시 부하 결과를 개인 사용의 반응 속도로 옮겨 읽지 않아요.

이 연결 예제는 Linux의 호환 NVIDIA CUDA⁷ 환경을 전제로 해요. 별도 가상환경⁸이나 장비용 컨테이너를 쓰고 PyTorch⁹·CUDA·드라이버 조합을 기록해요. DGX Spark는 ARM64·Blackwell 지원 빌드가 필요하고 x86 이미지를 그대로 쓰지 않아요. Mac의 CPU/MLX와 커뮤니티 vllm-metal은 CUDA 서버와 별도 경로예요.

처음에는 Qwen2.5-1.5B-Instruct로 모델 적재와 응답을 확인해요. 4096 문맥과 동시 요청 하나는 연결 점검값이지 최신 모델 권장치나 최고 속도 설정은 아니에요. 첫 다운로드와 준비 시간은 요청 생성 속도와 분리해요.

첫 명령으로 서버가 모델을 올리고 준비됐다는 메시지를 내면 다른 터미널에서 curl 요청을 실행해요. 정상 답변이 돌아오면 편집기나 채팅 앱의 OpenAI 호환 서버 주소를 http://127.0.0.1:8000/v1로 지정해요. 두 명령의 모델 ID와 포트가 같아야 같은 서버로 연결돼요.

실제 모델을 고르면 파일명·revision·정밀도·문맥 길이를 기록해요. NVFP4¹⁰와 GGUF¹¹ Q4는 모두 4비트라도 서로 바꾸어 쓸 설정이 아니며 GPU 세대·모델 구조·런타임¹²의 지원이 필요해요. 가중치 외에도 입력 KV cache와 계산 여유 공간이 필요해요.

--max-model-len은 입력과 출력의 전체 문맥 상한이고 --max-num-seqs 1로 요청 하나부터 확인해요. --gpu-memory-utilization을 높이면 KV cache 등에 더 많은 공간을 배정할 수 있지만 OS나 다른 프로세스의 여유가 줄어요. 오류가 나면 문맥과 동시 요청을 한 번에 하나씩 낮춰 원인을 찾아요.

요청이 많아지면 합산 처리량은 늘 수 있지만 한 사람의 완료 시간은 길어질 수 있어요. 개인 코딩 보조에서는 처리량보다 첫 토큰부터 코드가 끝날 때까지를 기록해요.

컨테이너나 가상환경에서 vLLM 0.30.0을 고정하고 vllm --version으로 확인해요. DeepSeek-V4-Flash-DSpark와 tokenizer가 장치·attention¹³ backend에서 지원되는지 봐요. 공식 예제의 deepseek_v4 tokenizer와 --trust-remote-code는 모델 제공 코드를 실행할 수 있으므로 출처와 실행 환경을 검토해요.

adaptive verification은 CUDA graph로 단계 비용을 측정해요. full cudagraph가 필요한 구성에서 --enforce-eager를 함께 쓰면 거부될 수 있고, 공식 문서는 LoRA¹⁴와 pipeline parallelism¹⁵ 제한도 안내해요. 모델·KV cache가 함께 들어갈 메모리, backend와 graph capture를 먼저 확인해요.

기본 모델 연결을 확인한 뒤 DeepSeek-V4-Flash target과 DSpark draft를 준비해요. 예제의 speculative token 수 7과 probabilistic sampling은 해당 문서 설정이지 다른 draft의 권장 깊이가 아니에요. target·draft가 실제로 선택됐는지 로그와 수락 통계도 확인해요.

이 절의 서버 예제는 모두 8000 포트를 사용해요. 앞의 작은 모델 서버를 Ctrl+C로 종료한 뒤 DeepSeek 서버를 시작하고, 요청 확인은 다른 터미널에서 해요. DSpark 설정으로 바꿀 때도 기존 서버를 먼저 종료하세요. 같은 GPU에서 이전 프로세스가 메모리를 유지하고 있다면 종료 상태를 확인한 뒤 다음 서버를 실행해요.

DSpark 배포본은 DeepSeek-V4-Flash 가중치에 추측 디코딩¹⁶ 모듈을 붙인 체크포인트¹⁷예요. 아래 DSpark 명령은 서버 모델과 초안 설정에 모두 deepseek-ai/DeepSeek-V4-Flash-DSpark를 지정해요. 서버를 바꾼 뒤에는 /v1/models에서 이 ID를 확인하고 이어지는 요청에도 같은 ID를 넣으세요. 앞의 기본 Flash 서버 요청은 기본 서버를 확인할 때 사용하면 됩니다.

같은 코드 수정 요청으로 동시 요청 하나와 여러 개를 시험해요. target·draft·입력/출력 길이·sampling·GPU·메모리를 고정하고 동시 요청 수만 바꿔 여러 번 재요. 모델 로딩과 CUDA graph capture 시간은 요청 처리와 별도로 적어요.

한 요청에는 TTFT¹⁸·토큰 사이 지연·완료 시간을, 서버 총 처리에는 완료 요청 수나 tokens/s를 적어요. acceptance 통계·GPU 메모리·preemption·OOM도 함께 봐요. 동시성이 늘어 throughput이 올라도 개인 요청 대기가 길어질 수 있어요.

릴리스 노트는 H200에서 graph capture가 약 12초에서 2초, engine init이 약 28.9초에서 8.2초로 줄었다고 설명해요. GC freeze 변경으로 모델을 처음 띄우는 준비 단계가 개선된 사례예요. 요청 중 응답 속도와 함께 서버 기동 시간도 기록하면 운영에서 어느 구간이 줄었는지 확인할 수 있어요.

기동 실패면 backend의 device-decided query length 지원, full cudagraph, LoRA·pipeline parallelism 조건부터 확인해요. 실행되지만 이득이 없다면 수락률, 동시 부하의 draft 경쟁, 짧은 출력의 준비 비용을 살펴보고 한 조건만 바꿔 다시 비교해요.

0.30.0 릴리스 및 adaptive verification 문서를 사용해 설치 버전과 모델·장치 지원을 확인해요. 최신 main 브랜치 문서나 컨테이너 태그는 0.30.0과 다를 수 있으니 실험할 버전 문서를 기준으로 해요.

vLLM 서버를 재시작하면 큰 모델 파일을 다시 읽고 GPU에 올리느라 기다려야 해요. 0.31.0의 vllm preload는 별도 데몬이 GPU의 모델 가중치를 유지하고, 새 서버 프로세스가 이를 재사용하도록 해요. 설정 변경이나 개발 때문에 같은 모델을 자주 재시작할 때 유용해요.

먼저 터미널 하나에서 데몬을 실행하고, 다른 터미널에서 --load-format ipc_cache를 지정해 서버를 시작해요. 아래는 Qwen3-8B를 GPU 한 장에서 실행하는 예예요. 모델·버전·병렬화·dtype·양자화¹⁹ 설정이 같아야 캐시를 재사용해요. 설정이 다르면 디스크에서 다시 읽어요.

preload 시험은 0.31.0 환경에서 따로 진행해요. 0.30.0 서버를 종료하고 0.31.0을 설치한 가상환경이나 컨테이너로 전환한 뒤 vllm --version을 확인하세요. 데몬과 서버를 시작할 두 터미널 모두 같은 0.31.0 환경을 사용해야 해요. 이전 서버가 8000 포트를 비운 뒤 아래 두 단계를 시작하면 됩니다.

preload 데몬이 실행되는 동안 모델 가중치는 GPU 메모리에 남아요. 서버만 종료하거나 재시작해도 유지돼요. 같은 GPU에서 다른 작업을 하려면 데몬이 실행되는 터미널에서 Ctrl+C를 눌러 종료한 뒤, nvidia-smi나 ROCm²⁰ 관리 도구로 메모리가 반환됐는지 확인해요.

이 기능은 CUDA·ROCm 환경의 텐서·전문가·데이터 병렬화를 지원해요. 파이프라인 병렬화는 지원하지 않고, 양자화 방식에 따라 UnsupportedQuantForIPCError가 날 수 있어요. Apple Silicon의 vllm-metal은 별도 프로젝트이므로 이 기능을 적용하지 않아요. preload는 재시작 대기 시간을 줄이는 기능이며 답변의 토큰 생성 속도는 별도로 측정해야 해요.