vLLM 로컬 설치 Apple Silicon 맥에서 OpenAI API 서버 띄우기

vLLM이 뭔데, 왜 맥에서 쓰기 힘든 건지

vLLM을 Apple Silicon 맥에 설치해서 OpenAI 호환 API 서버로 띄우는 방법을 정리했다. vLLM-Metal 플러그인 설치부터 모델 실행, curl과 Python 호출 예제까지 바로 복사해 쓸 수 있게 만들었다. 나중에 또 까먹을까 봐.

vLLM은 UC Berkeley에서 시작된 오픈소스 LLM 추론 엔진이다. 핵심은 PagedAttention이라는 기술인데, KV 캐시를 페이지 단위로 관리해서 GPU 메모리를 거의 낭비 없이 쓸 수 있다. 기존 방식은 시퀀스 길이에 따라 메모리를 미리 할당해놓고 쓰다 보니까 빈 공간이 많았거든. vLLM은 그걸 페이지 테이블처럼 필요할 때마다 할당하는 방식이라서 실제 서빙 처리량이 2~4배 높게 나온다.

Continuous Batching이라는 것도 있다. 요청이 들어오는 즉시 실행 중인 배치에 끼워넣는 방식이라서, 이전 요청 끝날 때까지 기다릴 필요가 없다. 실시간 서빙 상황에서 체감 차이가 꽤 크다.

지원 기능도 방대하다. 양자화(FP8, INT8, INT4, GPTQ, AWQ, GGUF 등), Speculative Decoding, 분산 추론(Tensor/Pipeline/Expert Parallel), OpenAI 호환 API, Multi-LoRA, 200+ 모델 아키텍처, 구조화된 출력, 툴 콜링까지. 솔직히 이 정도면 상용 API 서비스 대체로 충분하다.

Apple Silicon 맥에서 쓰는 법 3가지

문제는 vLLM이 원래 CUDA 기반이라서 Apple Silicon에서는 그냥 안 돌아간다는 거다. 근데 세 가지 경로가 있다.

vLLM-Metal 플러그인 (권장)

vllm-metal이라는 커뮤니티 플러그인이 있다. MLX를 백엔드로 써서 Metal GPU를 활용하는 방식이다. v0.2.0부터 Unified paged varlen Metal kernel이 기본 어텐션 백엔드로 들어가면서 TTFT가 83배, 처리량이 3.6배 올랐다.

설치는 한 줄이면 된다:

curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash

이렇게 하면 ~/.venv-vllm-metal에 가상환경이 만들어진다. 활성화하고 바로 쓰면 된다:

source ~/.venv-vllm-metal/bin/activate
vllm serve Qwen/Qwen3-4B --device metal

지원 모델은 텍스트 전용이긴 한데, 꽤 다양하다:

• Qwen3: 완전 지원 (4B, 8B 등)
• Qwen3.5 / 3.6 / Next: Hybrid Mamba+Attention 구조까지 지원
• Gemma 3: 1B~4B 검증됨
• Llama 3: 1B~8B 검증, 4bit 양자화로 16GB Mac에서도 동작
• Mistral-7B: 4bit로 16GB Mac에서 확인됨
• DeepSeek-R1-Distill: 1.5B, 7B 검증
• Phi-4-mini: 검증 완료
• Qwen2.5: 3B~14B 검증

제한사항: 멀티모달(비전, 오디오 입력)은 아직 안 된다. CUDA 전용 최적화인 Tensor Parallel 같은 것도 안 된다.

CPU 모드 (비권장)

pip install vllm
VLLM_TARGET_DEVICE=cpu vllm serve Qwen/Qwen3-4B

Metal GPU를 안 쓰니까 느리다. 가벼운 테스트 용도로만.

MLX-LM 직접 사용 (서빙 기능 필요 없으면)

pip install mlx-lm
mlx_lm.generate --model mlx-community/Qwen3-4B-4bit --prompt "안녕"

서빙도 된다:

mlx_lm.server --model mlx-community/Qwen3-4B-4bit --host 0.0.0.0 --port 8080

가볍고 빠르고 셋업이 간단하다. 대신 vLLM의 Continuous Batching이나 Multi-LoRA 같은 고급 기능은 없다.

vLLM-Metal로 OpenAI 호환 API 서버 띄우기

이게 실제로 가장 쓸 만한 케이스다. 로컬에 서버 띄워놓고 다른 앱에서 OpenAI SDK로 호출하는 구조.

Apple Silicon은 Unified Memory라서 VRAM이 따로 없고 RAM을 공유한다. 모델 크기 선택이 중요한데, 16GB Mac은 4bit 양자화 7B급(Qwen3-4B-4bit, Llama3-8B-4bit)이 현실적이고, 24GB면 14B급 4bit, 64GB면 70B급 4bit도 돌아간다. FP16 기준으로는 7B가 약 14GB 필요하니까, 16GB Mac에서 4bit 양자화가 거의 필수다.

서버 실행:

source ~/.venv-vllm-metal/bin/activate
vllm serve mlx-community/Qwen3-4B-4bit \
--device metal \
--host 0.0.0.0 \
--port 8000 \
--api-key local-test

서버가 뜨면 curl로 호출할 수 있다:

curl http://localhost:8000/v1/chat/completions \
-H "Authorization: Bearer local-test" \
-H "Content-Type: application/json" \
-d '{
"model": "mlx-community/Qwen3-4B-4bit",
"messages": [{"role": "user", "content": "안녕"}]
}'

Python OpenAI SDK로도 바로 된다:

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="local-test")
response = client.chat.completions.create(
model="mlx-community/Qwen3-4B-4bit",
messages=[{"role": "user", "content": "파이썬으로 피보나치 짜줘"}]
)

이러면 로컬 LLM을 쓰면서도 OpenAI 에코시스템(LangChain, LlamaIndex, AutoGen 등)을 그대로 활용할 수 있다.

한계와 언제 쓰면 되나

vLLM-Metal이 생각보다 잘 만들어져 있긴 한데, 체감되는 한계가 있다.

우선 멀티모달이 안 된다. 비전 모델이나 오디오 입력은 아직 지원 안 한다. 이미지 인식이 필요하면 Ollama를 써야 한다. 그리고 커뮤니티 플러그인이라서 메인 vLLM 업데이트 따라잡기가 버겁다. vLLM이 새 버전 나올 때마다 Metal 플러그인도 맞춰야 하는데, 항상 바로 안 된다. CUDA 대비 연산 성능은 당연히 떨어진다. Unified Memory 구조라서 VRAM 병목은 없지만, 연산 자체는 NVIDIA H100 같은 걸 못 따라간다.

그래도 이런 상황에는 확실히 좋다:

• 로컬에서 OpenAI 호환 API 서버가 필요할 때
• 개발/테스트 환경에서 빠르게 LLM 붙여야 할 때
• 데이터 유출 걱정 없이 로컬에서 돌리고 싶을 때
• 배치 처리나 Multi-LoRA 서빙이 필요할 때

반대로 간단한 추론만 하면 MLX-LM이 더 가볍고, 비전/오디오가 필요하면 Ollama가 아직 더 낫다. 대규모 트래픽 서빙은 결국 NVIDIA GPU 클러스터가 필요하다.

---

📎 참고 자료

• vLLM 공식 설치 가이드
• vLLM-Metal GitHub 저장소
• vLLM GitHub 저장소

---

📌 함께 보면 좋은 글

• Cerebras AI 칩 IPO 첫날 주가 108% 폭등 외 16건 — Interaction Brief 5월 15일
• Cerebras AI 칩 IPO 첫날 주가 108% 폭등 외 16건 — Interaction Brief 5월 15일
• Cerebras AI 칩 IPO 첫날 주가 108% 폭등 외 16건 — Interaction Brief 5월 15일