Mac 上跑 vLLM:pip 装不了,Metal 走插件
在 Apple silicon 上 pip install vllm 报 CUDA_HOME,凡是说能直接装的教程都是 Linux 环境写的。
📜 目录
能走的路有三条,而且互相不能替换。pip install vllm 在 Mac 上根本装不上:0.34.0 在 PyPI 上只挂了两个 wheel,全是 Linux 的。官方 CPU 版本只能从源码编,编出来跑在 CPU 上。要用 Metal,得靠一个 2025 年 12 月由维护者拉起来的插件。
下面每条命令、每个数字都来自项目自己的文档、PyPI 文件和 issue,读取日期 2026 年 11 月 21 日。写这篇时手上没有 Mac,所以这里没有任何吞吐数字,只有每条路装了什么、支持什么。
三条路摆在一起
| 路径 | 装的是什么 | 算力 | 有没有预编译 | macOS 下限 |
|---|---|---|---|---|
| pip install vllm | 装不出能用的东西 | 无 | 没有 macOS wheel | — |
| 源码编 CPU 版 | vLLM 0.34.0,本地编译 | CPU,FP32 / FP16 | 无 wheel,无镜像 | Sonoma |
| vLLM Metal 插件 | vllm-metal,带预编译 wheel | GPU,走 MLX | brew tap 或安装脚本 | 15 |
第一条:pip install vllm 为什么在 Mac 上失败
看 vllm 0.34.0 在 PyPI 上挂的文件:vllm-0.34.0-cp38-abi3-manylinux_2_28_x86_64.whl 228.0 MB,vllm-0.34.0-cp38-abi3-manylinux_2_28_aarch64.whl 227.9 MB,加一个 48.5 MB 的源码包。没有任何 macosx 标签,所以 pip 退回源码包,然后开始对着 CUDA 编译。
这个失败在 issue 里挂了三年:issue #1441,2023 年 10 月 21 日开的,报的是在 Mac 上直接 pip install vllm 之后 RuntimeError: Cannot find CUDA_HOME. CUDA must be available to build the package。第二天就关了,而这个答案三年没变:macOS 上不存在走 pip 的 GPU 版本。
第二条:官方 CPU 版,确实存在
vLLM 文档里现在有一页 Apple silicon,措辞很直接:macOS 支持属于实验性,必须从源码构建,CPU 实现只支持 FP32 和 FP16。要求是 macOS Sonoma 或更新、Xcode 15.4 或更新并装好命令行工具、Apple Clang 15.0.0 以上。没有预编译的 Apple silicon wheel,也没有预编译镜像。
git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install -r requirements/cpu.txt
uv pip install -e .
macOS 上 VLLM_TARGET_DEVICE 会自动设成 cpu,这也是这套构建唯一支持的设备。文档里点了两个值得提前知道的报错。报 'map' file not found 这类标准头找不到,是命令行工具装坏了,重装即可。报 'constexpr' is not a type,是构建体系用了旧的 C++ 标准,在 cmake/cpu_extension.cmake 里加一行 set(CMAKE_CXX_STANDARD 17)。macOS CPU 构建只在 CI 的最新 Apple silicon runner 上做过冒烟测试,其他 macOS 和 Clang 版本属于尽力而为。
编完之后拿到的是:vLLM 的调度器、分页注意力和 OpenAI 兼容服务,跑在 CPU 上。放在笔记本上,这是个验证代码的环境,不是对外服务的环境。文档里没有任何吞吐承诺。
第三条:vLLM Metal,从 MPS 需求里长出来的插件
issue #29629,标题就是「vLLM with MPS Support」,2025 年 11 月 27 日开的,要的正是这个。2025 年 12 月 12 日维护者回帖说,后续的硬件后端都该走插件接口,他已经建了 vllm-project/vllm-metal 仓库放在那边做。issue 于 12 月 17 日关闭。
那个插件就是现在的 Metal 路线。Apache-2.0,2,008 星,最后一次推送是 2026 年 11 月 20 日,属于在维护的项目,不是弃坑。计算后端用 MLX,上面套的仍是 vLLM 的引擎、调度器和 OpenAI 兼容 API。
brew tap vllm-project/vllm-metal https://github.com/vllm-project/vllm-metal
brew install vllm-project/vllm-metal/vllm-metal
另一条是安装脚本,项目自己的 recipes 都按它写:
curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash
source ~/.venv-vllm-metal/bin/activate
安装文档里有两处限制容易被漏掉:必须是 Apple Silicon,macOS 15 或更新;pip install vllm-metal 明确不支持。两种方式默认都用 Python 3.12 加预编译 wheel,不需要编译器。想要稳定版而不是开发版,脚本后面加 bash -s -- --stable。
项目唯一公布的容量参考
recipes 按 Mac 内存分档,等于替你把模型选好了。这大概是目前最接近「支持硬件清单」的东西:
| Mac 内存 | 跑哪个模型 | 首次下载 | max-model-len | max-num-batched-tokens |
|---|---|---|---|---|
| 16 GB | Qwen3.5-9B-MLX-4bit | 6.0 GB | 8192 | 2048 |
| 32 GB | Qwen3.5-27B-4bit | 16 GB | 32768 | 1024 |
| 64 GB | Qwen3.5-35B-A3B-4bit | 20 GB | 32768 | 不设 |
表旁边的注解才是有用的部分。16 GB 那档写着「不设这个模型装不下」,指的是 --max-num-batched-tokens 2048,把长文本分成更小的步来读,压低峰值内存。32 GB 那档,27B 能开 32k 窗口,但文档直说它读长文本慢,要快就换 9B。两条指向同一个取舍:在 Mac 上,上下文长度和回复速度是从同一块内存里出的,而这块内存桌面上的其他程序也在用。
该走哪条
如果目的是在本机 GPU 上跑 vLLM 的 API 和调度器,插件是唯一的路,brew tap 是文档里最短的安装方式。如果目的是 Mac 上出 token 最快,那就别用这套:llama.cpp 和 MLX 是直接调引擎的,vLLM Metal 本身也是套在 MLX 外面。如果目的是给将来要跑在 CUDA 上的代码做测试架子,CPU 版最忠实,只是慢。
同一个引擎在 CUDA 上的部署步骤,在 vLLM 部署指南;和 Ollama、TGI 的引擎对比在 vLLM 对 Ollama 对 TGI。缓存本身要多少显存,按模型和上下文长度的表在 KV cache 显存表。
这篇没有回答的
这里没有一个吞吐、延迟或显存数字是实测的。recipes 给了模型、上下文和批处理参数,但没有公布 token 速率;自己编一个 M 系列笔记本对 H100 的对比,属于那种会被引用好几年、却从来没成立过的数字。挑一条路装上,用自己的题集跑一遍,跟你原来用的引擎比。
相关文章
本站文章由编辑人工撰写,收录的工具均经过实测或公开资料核验。文中链接指向工具官网或 GitHub 仓库,仅作信息参考,不构成付费推广。