vLLM 가속¶

vLLM은 높은 처리량(High-throughput)과 메모리 효율성을 자랑하는 LLM 서빙 엔진입니다. llama.cpp가 광범위한 호환성과 저사양 환경에 초점을 맞춘다면, vLLM은 고사양 GPU에서의 프로덕션급 성능을 위해 설계되었습니다.

vLLM이란 무엇인가요?¶

• 저장소: github.com/vllm-project/vllm

• 핵심 혁신: PagedAttention.

전통적인 어텐션(Attention) 알고리즘은 연속된 메모리 블록을 필요로 하며, 이는 상당한 메모리 파편화와 낭비(최대 60-80%)를 초래합니다. vLLM은 운영체제의 가상 메모리 페이징에서 영감을 받은 PagedAttention 알고리즘을 도입했습니다. 이를 통해 KV 캐시 블록을 비연속적인 메모리 공간에 저장할 수 있게 되었습니다.

주요 이점¶

• 더 높은 처리량: 표준 Hugging Face Transformers보다 훨씬 더 많은 동시 요청을 처리할 수 있습니다.

• 메모리 효율성: GPU VRAM 낭비가 거의 제로에 가까워, 더 큰 배치 크기(Batch size)나 더 긴 컨텍스트 윈도우를 사용할 수 있습니다.

• 빠른 기능 도입: 연속 배칭(Continuous batching)이나 AWQ, GPTQ, SqueezeLLM 양자화 같은 새로운 서빙 기능을 가장 먼저 지원하곤 합니다.

Backend.AI GO에서의 역할¶

Backend.AI GO에서 vLLM은 주로 NVIDIA GPU를 사용하는 사용자(Linux x86_64 또는 arm64 환경)를 위한 "프로(Pro)" 엔진 역할을 합니다.

언제 vLLM을 사용해야 하나요?¶

다음과 같은 경우 vLLM 백엔드로 전환을 고려해보세요:

1. VRAM이 넉넉한 NVIDIA GPU 보유: RTX 5090 (32GB), 전문가용 RTX Pro 6000 (96GB), 또는 DGX Spark (GB10, 128GB) 개인용 AI 워크스테이션에서 vLLM이 최고 성능을 냅니다.

2. 동시성(Concurrency)이 중요할 때: Backend.AI GO를 여러 사용자나 여러 에이전트를 위한 서버로 활용하고 있을 때.

3. 지연 시간보다 처리량이 중요할 때: 엄청난 양의 텍스트를 처리해야 해서(예: 수백 개의 문서 요약), "첫 토큰 생성 시간"보다 "전체 완료 시간"이 더 중요할 때.

호스트 요구 사항¶

vLLM은 Linux 컨테이너 안에서 실행되므로, 엔진 페이지는 vLLM 옵션을 제공하기 전에 준비 상태를 확인합니다.

확인 항목:

• Docker(또는 지원되는 다른 컨테이너 런타임)의 설치 여부.
• NVIDIA GPU를 컨테이너에 전달할 수 있는지 확인합니다.
• 선택한 모델이 사용 가능한 VRAM에 맞는지 여부.

차단 조건이 발견되면, 엔진 페이지는 알기 쉬운 설명과 단계별 해결 방법(예: "Docker 설치" 또는 "NVIDIA Container Toolkit 설치")이 포함된 배너를 표시합니다. 조건이 해결될 때까지 해당 옵션은 비활성화됩니다.

설정 방법¶

Backend.AI GO에서 vLLM을 사용하려면:

1. 먼저 엔진에서 vLLM 엔진을 설치합니다.

2. 설정 > 모델로 이동해 포맷별 기본 엔진을 확인합니다.

3. 모델 > Hugging Face 탐색에서 앱이 safetensors-repo로 분류하는 Hugging Face 저장소를 다운로드합니다.

4. 모델을 실행할 때 vLLM 엔진을 선택하거나, 해당 형식의 기본 엔진으로 vLLM을 지정합니다.

5. 호스트에 Docker와 필요한 NVIDIA 컨테이너 스택이 준비되어 있는지 확인합니다.

지원 모델 형식¶

.gguf를 사용하는 llama.cpp와 달리, vLLM은 다음 형식들을 직접 지원합니다:

• Hugging Face 표준 형식: 일반적인 .safetensors 또는 .bin 가중치 파일.

• AWQ / GPTQ: 더 빠른 추론을 위해 사전 양자화된 모델들.

Backend.AI GO가 vLLM을 실행하는 방식¶

컨테이너 실행은 Backend.AI GO가 담당하므로 docker run을 직접 실행할 필요가 없습니다. 다운로드한 Hugging Face safetensors 저장소를 vLLM 엔진으로 실행하면 Backend.AI GO는 다음을 수행합니다:

1. 처음 사용할 때 이미지 버전에서 설명하는 태그로 vllm/vllm-openai 이미지를 다운로드합니다. 이 이미지는 크기가 커서(약 9~10GB) 첫 시작에서는 이미지를 다운로드하고 준비하는 데 시간이 걸린 뒤에 모델이 로드됩니다. 이후 시작에서는 캐시된 이미지를 재사용합니다.

2. GPU 전달(--gpus all), 공유 메모리 전송(--ipc=host), 읽기 전용으로 마운트한 모델, 루프백에 게시한 호스트 포트로 컨테이너를 실행합니다.

3. 직접 실행하는 vLLM에서 자주 빠뜨리는 실행 플래그를 설정해 흔한 실패를 막습니다:

   • --served-model-name을 라우터가 노출하는 별칭과 맞춰, 모델 id로 보낸 요청이 엔진에 도달합니다.
   • --max-model-len을 컨텍스트 설정에서 유도해, max_tokens가 모델 길이를 초과하는 요청을 방지합니다.
   • --enable-auto-tool-choice와 도구 호출 파서로 tool_choice: auto가 동작하게 해, 도구 사용 요청이 400 오류를 만나지 않습니다. 모델에 다른 파서를 지정하지 않으면 hermes를 사용합니다(모델별 실행 설정 참고).
   • --gpu-memory-utilization은 안전한 기본값 0.90을 사용하며, 설정에서 모든 컨테이너 엔진의 값을 바꾸거나 모델별로 따로 지정할 수 있습니다.

컨테이너가 /health에서 정상으로 보고하면 Backend.AI GO가 라우터에 등록하고, 모델은 채팅 UI와 관리 API 모두에서 /v1/chat/completions에 응답합니다. 모델을 중지하면 컨테이너를 정리하고 경로 등록을 해제합니다. 예기치 않은 충돌도 같은 방식으로 회수하므로 끊긴 경로가 남지 않습니다.

모델별 실행 설정¶

최근 모델 카드는 위에 나온 플래그 말고도 모델의 도구 호출 형식에 맞는 파서, 추론 파서, GPU에 맞는 MoE 커널, 추측 디코딩용 초안 모델 같은 vllm serve 플래그를 요구하는 경우가 많은데요, 이런 값은 모델 설정 창의 vLLM 탭에서 모델별로 지정합니다. 이 탭은 다운로드한 Hugging Face safetensors 저장소에만 나타나고, 각 설정은 플래그 하나에 대응하며, 설정하지 않은 항목은 플래그를 추가하지 않으므로 한 번도 설정하지 않은 모델은 이전과 똑같이 실행됩니다.

드롭다운에는 vLLM v0.31.0에 들어 있는 이름만 나오고, 앱은 저장할 때와 모델을 시작할 때 모두 그 밖의 값을 거부하므로 설정으로 컨테이너 명령에 임의의 플래그를 넣을 수는 없습니다. 자유 형식 인수 칸도 따로 두지 않았죠. 더 오래된 이미지 태그를 사용하는 경우, 해당 릴리스가 모르는 이름을 지정하면 vLLM이 자체 오류 메시지와 함께 시작 단계에서 종료됩니다.

초안 모델은 vLLM이 컨테이너 안에서 다운로드하는데, 컨테이너는 모델을 중지할 때 삭제되기 때문에 모델을 시작할 때마다 다시 다운로드합니다. GPU 메모리 비율, 텐서 병렬 크기, MoE 백엔드, Mamba 백엔드는 호스트의 GPU에 따라 달라지는 값이라 .baimodel로 내보낼 때는 포함되지 않습니다.

예를 들어 nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4 모델 카드에 있는 DGX Spark(GB10) 실행 예시는 다음 설정에 대응합니다.

이 설정은 vLLM 엔진이 모델을 실행할 때만 적용되고, SGLang이 실행하는 경우에는 무시됩니다.

이미지 버전¶

이번 릴리스는 vllm/vllm-openai:v0.31.0을 고정해 사용하는데, 해당 이미지는 x86_64(amd64)와 arm64용으로 모두 배포되므로 GB10 DGX Spark나 GH200 호스트에서도 같은 엔진이 실행됩니다. 기본 태그는 CUDA 13 빌드라서 R580 브랜치 이상의 NVIDIA 드라이버가 필요하고, 드라이버가 그보다 오래된 호스트에서는 아래 방법으로 이미지 태그를 vLLM이 같은 릴리스에 함께 배포하는 CUDA 12.9 빌드인 v0.31.0-cu129로 바꿔야 합니다.

다른 태그를 사용하려면 설정 > 엔진에서 vLLM 카드의 이미지 태그 칸에 태그를 입력하고 저장을 선택하세요. vllm/vllm-openai: 부분을 빼고 태그만 입력해야 하며, 칸을 비워 두고 저장하면 기본 태그로 돌아갑니다. 저장한 태그는 카드의 이미지 상태와 이미지 다운로드, 이미지 업데이트, 모델 실행에 모두 사용되므로, 받아 둔 이미지가 곧 모델이 실행되는 이미지입니다. CLI에서도 같은 설정을 바꿀 수 있습니다.

# v0.31.0-cu129를 vLLM 이미지 태그로 저장하고 다운로드
aigo engine container image pull vllm --tag v0.31.0-cu129

# 기본 태그로 되돌리기
aigo engine container image pull vllm --reset-tag

# 준비 상태 보고서에서 실행 시 받을 이미지 확인
aigo engine container readiness --json '{"engineId":"vllm"}'

준비 상태 보고서의 image 필드에는 이미지 레퍼런스(imageReference), 기본 태그(defaultTag), 사용자가 지정한 태그가 적용되었는지 여부(tagOverridden)가 표시되고, aigo engine container image inspect vllm도 같은 두 필드를 보여 줍니다.

vLLM은 데이터센터급 추론 성능을 여러분의 고성능 워크스테이션으로 가져옵니다.