waybarrios/vllm-mlx

vllm‑mlx – 在 Apple Silicon 上實現高吞吐量 LLM 服務

是什麼

• 一個即插即用的 vLLM 風格推理伺服器，使用 MLX 框架與 Metal 內核，直接在 Apple Silicon GPU 上執行大型語言模型（及多模態模型）。
• 整合了原始 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 Schema 的結構化輸出。
效能	連續批次處理，分頁 KV 快取，前綴快取，可選 SSD 分層 KV 快取，預熱提示預載入（首 token 速度提升 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 tokens/s，3 B 4 位模型約 206 t/s，30 B 4 位 MoE 模型約 128 t/s。
• 語音轉文字：Whisper‑tiny 達 197× 實時，Whisper‑large‑v3‑turbo 達 55×，Whisper‑large‑v3 達 24×。

使用情境

• 無需雲端 GPU 即可在 MacBook 上本地開發 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 社群積極維護；歡迎貢獻（修復 bug、效能優化、新增基準測試等）。

---

簡而言之，vllm‑mlx 將 vLLM 的高吞吐量服務能力帶到 Apple Silicon，提供熟悉的 OpenAI/Anthropic API，同時支援文字、視覺、音訊與嵌入——全部無需離開 Mac 生態系。