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 生态系统。