vllm-mlx
무엇인가
vllm-mlx는 Apple Silicon Mac에서 LLM·비전·오디오·임베딩 모델을 서빙하는 추론 서버다. vLLM의 continuous batching과 paged KV 캐시 설계를 MLX 위에 옮긴 것으로, 로컬 추론 런타임 계열에 속한다. 하나의 프로세스가 OpenAI 호환 엔드포인트와 Anthropic 호환 엔드포인트를 동시에 노출한다.
어떻게 동작하나
추론은 Apple의 MLX와 Metal 커널 위에서 unified memory로 수행하며 모델 변환 단계를 두지 않는다. 요청은 continuous batching으로 묶여 처리되고, KV 캐시는 페이지 단위로 관리되며 trie 기반 prefix cache가 요청 간 접두사를 공유한다. 접두사 캐시는 --ssd-cache-dir로 디스크에 spill되고, --warm-prompts로 인기 접두사를 기동 시 미리 적재한다. 라우팅은 /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/rerank, /v1/responses와 Anthropic /v1/messages로 나뉜다. 도구 호출은 19종 파서로 처리하고, response_format의 JSON Schema는 lm-format-enforcer로 강제한다.
무엇과 다른가
Ollama나 mlx-lm을 직접 쓰는 구성과 달리 배치 스케줄러와 페이지 단위 KV 캐시를 서버 안에 둔다. OpenAI와 Anthropic 두 프로토콜을 한 프로세스에서 처리하므로 Claude Code 같은 Anthropic 클라이언트와 OpenAI SDK 클라이언트를 같은 서버에 붙일 수 있다. vLLM 자체는 CUDA 중심이라 Apple Silicon에서 그대로 돌지 않는다.
어떻게 쓰나
설치는 uv를 권장하고 pip와 소스 빌드 경로도 제공한다. 서버를 띄운 뒤 OpenAI SDK는 base_url을, Anthropic SDK와 Claude Code는 /v1/messages 엔드포인트를 향하게 한다. --metrics를 주면 /metrics에서 Prometheus 지표를 내보내고, vllm-mlx bench-serve로 프롬프트 스윕을 돌려 CSV·JSON으로 결과를 받는다.
전제와 한계
Apple Silicon(M1~M5) 전용이며 MLX와 Metal을 요구한다. 추론 파서는 Qwen3, DeepSeek-R1, DeepSeek-V4를 대상으로 하고, MoE 전문가 축소는 --moe-top-k, Qwen3-Next 투기적 디코딩은 --mtp 플래그로 켠다. 내장 리랭커는 BERT/XLM-RoBERTa sequence-classification 가중치에서 gelu, gelu_new/gelu_fast, relu, silu/swish 활성화만 처리하고 나머지 활성화는 명시적으로 실패한다.
관련 논문 5
유사 도구
- Rapid-MLXApple Silicon에서 MLX로 모델을 돌리며 OpenAI·Anthropic 호환 엔드포인트를 여는 로컬 추론 서버다. 클라이언트 수정 없이 교체한다.
- mlx-serveApple Silicon에서 MLX와 GGUF 모델을 실행하는 Zig 네이티브 추론 서버다. OpenAI·Anthropic·Ollama API를 한 포트에서 동시에 제공한다.
- claude-code-localApple Silicon에서 MLX로 로컬 모델을 돌려 Claude Code에 연결하는 Anthropic API 네이티브 서버다. 번역 프록시 없이 한 프로세스로 동작한다.
- MTPLXApple Silicon에서 모델 자체의 MTP 헤드로 Qwen 3.8을 가속 실행하는 Mac 앱·CLI다. OpenAI·Anthropic 호환 서버를 로컬에 띄운다.
- Atomic-Chat오픈웨이트 LLM을 로컬에서 실행하고 OpenAI 호환 서버로 노출하는 데스크톱 앱이다. llama.cpp와 MLX 엔진을 앱 안에서 전환한다.
- LLM-API-Key-ProxyOpenAI·Anthropic 호환 엔드포인트를 하나 띄워 여러 LLM 제공자를 provider/model 형식으로 중계하는 자체 호스팅 FastAPI 프록시다.