waybarrios/vllm-mlx

vllm‑mlx – Apple Silicon에서 고처리량 LLM 서빙

무엇인가요

• MLX 프레임워크와 Metal 커널을 사용하여 Apple Silicon GPU에서 대규모 언어 모델(다중 모달 모델 포함)을 직접 실행하는 vLLM 스타일의 즉시 사용 가능한 추론 서버입니다.
• 원본 vLLM 프로젝트의 여러 성능 최적화 기술(연속 배치, 페이지 기반 KV 캐시, 접두사 공유, 선택적 SSD 기반 캐시)을 통합하여, 낮은 지연 시간으로 많은 동시 요청을 처리할 수 있습니다.
• OpenAI 호환(/v1/chat/completions, /v1/completions, /v1/embeddings 등) 및 Anthropic 호환(/v1/messages) REST API를 제공하여 기존 클라이언트 라이브러리가 변경 없이 사용 가능합니다.

왜 중요한가요

• Apple의 M 시리즈 칩은 강력한 GPU 코어를 갖추고 있지만, 대부분의 오픈소스 LLM 서버는 CUDA를 타겟으로 합니다. vllm‑mlx는 모델을 다른 형식으로 변환하지 않고도 네이티브 Metal 백엔드를 활용할 수 있게 해줍니다.
• 연속 배치와 페이지 기반 KV 캐시는 특히 긴 컨텍스트나 다중 대화 시나리오에서 처리량과 메모리 사용량을 크게 향상시킵니다.
• 비전, 오디오, 임베딩의 내장 지원으로 단일 프로세스에서 텍스트 전용 LLM, 비전-언어 모델, 음성-텍스트, 텍스트-음성, 벡터 검색 임베딩을 모두 제공할 수 있습니다.

주요 기능 (README에 설명됨)

카테고리	주요 기능
API	OpenAI 호환 엔드포인트(/v1/*), Anthropic /v1/messages, 19개의 다른 모델 패밀리용 도구 호출 파서, JSON 스키마 기반 구조화 출력.
성능	연속 배치, 페이지 기반 KV 캐시, 접두사 캐시, 선택적 SSD 타이어드 KV 캐시, 웜 프롬프트 프리로딩(1.3–2.25배 빠른 첫 토큰), MoE top-k 축소, 사전 추론, 희소 프리필.
다중 모달	비전 모델(Gemma 3/4, Qwen3‑VL, Pixtral, Llama‑vision), 이미지/비디오/오디오 입력, 내장 TTS(11개 음성, 15개 이상 언어) 및 STT(Whisper 패밀리, M4 Max에서 최대 197배 실시간).
고급 추론	추론 추출 파서, MoE 전문가 축소, 사전 추론, 주의 기반 프리필.
관측성	Prometheus 메트릭 엔드포인트, 내장 벤치마크 CLI(vllm‑mlx bench‑serve).
하드웨어	Apple Silicon 전용(M1–M5), MLX/Metal 경유, 통합 메모리, 모델 변환 단계 없음.

일반적인 워크플로우

1. 설치 – pip install vllm-mlx (또는 uv tool install vllm-mlx). 선택적 오디오 기능은 pip install vllm-mlx[audio]로 추가.
2. 서버 시작 – 예: vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit --port 8000 --continuous-batching.
3. 호출 – OpenAI Python SDK 또는 Anthropic SDK를 http://localhost:8000/v1에 연결(API 키 필요 없음). README에는 최소한의 채팅 예제와 재순서화용 curl 예제가 포함되어 있습니다.
4. 선택적 기능 – 웜 프롬프트 로딩, SSD 캐시 디렉터리, MoE top-k, 사전 추론, 도구 호출, 다중 모달 페이로드, TTS/STT 유틸리티, 임베딩 모델 등.

성능 수치(M4 Max, 128 GB)

• LLM 디코딩 속도: 0.6 B 8비트 모델 기준 최대 약 418토큰/초, 3 B 4비트 모델 기준 약 206t/s, 30 B 4비트 MoE 모델 기준 약 128t/s.
• 음성-텍스트: Whisper‑tiny는 197배 실시간, Whisper‑large‑v3‑turbo는 55배, Whisper‑large‑v3는 24배.

사용 사례

• 클라우드 GPU가 필요 없이 맥북에서 LLM 기반 앱의 로컬 개발.
• 단일 통합 API를 필요로 하는 다중 모달 에이전트(텍스트 + 이미지 + 오디오) 프로토타이핑.
• Apple 하드웨어에서 민감한 데이터에 대한 사전 오프라인 추론 실행.
• 비CUDA GPU에서 연속 배치 및 KV 캐시 전략에 대한 벤치마킹 및 연구.

설치 및 시작하기

# 추천: uv 설치(시스템 전체 CLI)
uv tool install vllm-mlx
# 또는 가상 환경에서 pip
pip install vllm-mlx
# 오디오 확장 기능
pip install vllm-mlx[audio]
brew install espeak-ng   # 비영어 TTS에 필요

전체 문서는 https://vllm-mlx.is-a.dev/ 에 호스팅되어 있으며, 서버 구성, 다중 모달 사용, 벤치마킹, 모델 획득에 대한 단계별 가이드를 포함합니다.

라이선스 및 커뮤니티

• Apache 2.0 오픈소스 라이선스.
• Wayner Barrios와 MLX 커뮤니티가 적극적으로 유지 관리 중이며, 기여 환영(버그 수정, 성능 개선, 새로운 벤치마크 등).

---

요약하면, vllm‑mlx는 vLLM의 고처리량 서빙 기능을 Apple Silicon에 가져오며, 익숙한 OpenAI/Anthropic API를 제공하면서도 텍스트, 비전, 오디오, 임베딩을 모두 맥 생태계 내에서 지원합니다.