vllm-mlx：在 Apple Silicon 上同时提供 OpenAI 与 Anthropic 两套接口的推理服务

它替代的不是 vLLM，而是裸跑的 mlx-lm

在 Mac 上跑本地模型，常见做法是 Ollama 或者直接用 mlx-lm。这两种方式都能把模型加载起来，但都缺少面向并发请求的调度层。vllm-mlx 补的正是这一层：README 把它与 Ollama、mlx-lm 直接使用做了区分，强调自己提供连续批处理、分页 KV cache、前缀缓存和 SSD 分层缓存。换句话说，如果你只是一个人、一个终端、一次问一句，这个项目的额外价值有限；它的价值在多个请求同时打进来的时候才显现。目标读者是那些想让本地 Mac 充当团队内小模型服务端，或者想在不改代码的前提下把 Claude Code 指向本地权重的人。

一个进程里塞进两套 API 协议

这是它最容易被低估的部分。OpenAI 兼容侧覆盖 /v1/chat/completions、/v1/completions、/v1/embeddings、/v1/rerank 和 /v1/responses；Anthropic 兼容侧是 /v1/messages，文档说明支持流式、工具调用和 system prompt。客户端只要改 base_url，不需要适配层。对 Claude Code 来说更直接，README 给的做法是设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY 两个环境变量，然后照常运行 claude 命令。工具调用方面列了 19 个解析器，覆盖 OpenAI、Anthropic、Gemini、Qwen、DeepSeek、Gemma 等格式，模型输出的工具调用语法由解析器翻译成统一结构。结构化输出走 response_format 的 json_schema，底层用 lm-format-enforcer 约束解码。

缓存分层决定了长上下文场景能不能用

前缀缓存是基于 trie 的，跨请求共享，这是连续批处理之外第二个影响吞吐的设计。SSD 分层缓存通过 --ssd-cache-dir 把前缀缓存落到磁盘，文档给出的目标场景是长上下文 agent，因为纯内存缓存撑不住反复出现的超长前缀。另有 --warm-prompts 在启动时预载热门前缀，README 标注的收益是 1.3 到 2.25 倍 TTFT。这些数字来自项目自己的文档，我没有复现，也不清楚测试条件。需要留意的是 SSD 缓存本身有取舍：磁盘读写会带来延迟，只有在前缀命中率足够高、且上下文长度足够大时，落盘才比重新计算划算。前缀短或请求之间几乎没有共享内容时，这一层只是增加复杂度。

从安装到第一条请求的实际路径

安装是 pip install vllm-mlx，启动命令形如 vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit --port 8000 --continuous-batching。注意 --continuous-batching 是显式开关，不是默认行为，README 的快速开始里专门把它写了出来。OpenAI SDK 侧把 base_url 指向 http://localhost:8000/v1，api_key 填任意值即可，模型名用 default。需要嵌入能力时，启动命令追加 --embedding-model，例如 mlx-community/all-MiniLM-L6-v2-4bit，调用时该模型名作为 embeddings.create 的 model 参数。推理模型加 --reasoning-parser qwen3，返回结果里 reasoning 与 content 分开存放。MoE 模型可用 --moe-top-k 减少专家数量。可观测性方面，加 --metrics 后暴露 /metrics 供 Prometheus 抓取。内置压测工具是 vllm-mlx bench-serve，支持 --concurrency、--prompts、--workload、--repetitions 和 --output，输出 CSV 或 JSON。

多模态与音频的边界藏在 extras 里

视觉侧列出的模型包括 Gemma 3、Gemma 4、Qwen3-VL、Pixtral 和 Llama vision，图像通过 image_url 内容块传入，音频走 audio_url 内容块。语音合成提供了 11 个音色、15 种以上语言，涉及 Kokoro、Chatterbox、VibeVoice、VoxCPM 几个模型；语音识别基于 Whisper 系列。但这里有个容易被忽略的前提：音频能力需要 pip install vllm-mlx[audio] 单独安装，非英语 TTS 还要在 macOS 上 brew install espeak-ng。也就是说默认安装拿不到这些功能。README 里 whisper 的 RTF 数字（tiny 197x、large-v3-turbo 55x、large-v3 24x）来自 M4 Max 128 GB 环境，换到内存更小的机器上，能加载哪个尺寸的模型本身就是问题。

重排序器的激活函数限制是个诚实的信号

文档对 /v1/rerank 的说明里有一段值得单独看：内置的 MLX reranker 前向路径支持标准 BERT 与 XLM-RoBERTa 序列分类权重，hidden_act 允许 gelu、gelu_new/gelu_fast、relu、silu/swish。其他激活函数会显式报错，项目给出的理由是希望自定义 reranker 架构去写专门的适配器，而不是静默地用错激活函数。这是一个明确的设计取舍：牺牲兼容广度换取失败可见性。对使用者来说，这意味着你不能随便拿一个 HuggingFace 上的 reranker 权重就指望跑起来，得先确认它的 hidden_act 落在支持列表里。这种把不支持的情况直接暴露出来的做法，比悄悄给出错误排序结果要好，但也确实缩小了可用模型范围。

什么时候它不是一个好选择

最硬的一条限制写在 README 里：Apple Silicon only，M1 到 M5，通过 MLX 走 Metal kernel。任何需要 Linux 服务器、需要 NVIDIA 卡、需要多机扩展的部署场景，这个项目都不适用，没有折中方案。第二条是模型来源，示例里清一色使用 mlx-community 组织下的量化权重，文档没有给出从原始权重转换到 MLX 格式的流程，所以你的私有微调模型能不能用，取决于社区是否已有对应转换或你是否自行处理。第三条是内存，统一内存意味着模型权重、KV cache 和系统占用共享同一块物理内存，M4 Max 128 GB 上跑 Qwen3-30B-A3B-4bit 约占 18 GB，这个数字在小内存机器上会直接决定你能开多大并发。第四条是版本节奏，最近的发布是 v0.4.1（2026-08-12），v0.4.0 在 2026-06-28，中间还有 v0.4.0rc1。功能面铺得很宽，从 TTS 到 rerank 到 MCP 工具解析都在同一个仓库里，这种广度通常意味着每个子系统的测试深度不一致，升级前值得看 release notes 里改了什么。

和 Ollama 的差别在调度层，不在模型层

拿 Ollama 作对照最能说明问题。两者都能在 Mac 上加载量化模型并对外提供 HTTP 接口，Ollama 的模型管理体验更成熟，拉取和切换模型一条命令搞定。差别在于并发请求的处理方式：Ollama 面向的是单用户交互式使用，而 vllm-mlx 把连续批处理、分页 KV cache、前缀共享作为核心卖点，README 也正是用这一点把自己和 Ollama 区分开。如果你的场景是几个人同时往一个本地端点发请求，或者你在跑 agent 循环会连续产生大量短请求，前缀缓存和批处理带来的差别会体现在等待时间上。反过来，如果只是自己偶尔问几句，Ollama 的成熟度和模型库覆盖更省事。另一个方向是直接写 MLX 代码，控制力最强，但连续批处理和缓存调度都得自己实现。

编辑结论

适合已经在用 M 系列 Mac、想让 Claude Code 或 OpenAI SDK 指向本地模型的人，也适合需要把视觉、语音、嵌入放在同一个进程里跑的实验性项目。不适合需要跨平台部署、多卡扩展或 CUDA 生态的团队，README 明确写了 Apple Silicon only。上手前先确认三件事：你的 macOS 与 Python 版本满足 3.10+；目标模型在 mlx-community 下有对应的 MLX 量化权重，因为文档没有给出转换流程；以及你要用的能力是否落在标注为 extras 的范围内，音频需要 pip install vllm-mlx[audio]，非英语 TTS 还需要 brew install espeak-ng。这三项任何一项不成立，后面的调优参数都没有意义。

官方来源

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. waybarrios/vllm-mlx on GitHub