Mac 上跑 vLLM:pip 装不了,Metal 走插件

📘 教程 2026-11-21 约 15 分钟阅读

在 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,带预编译 wheelGPU,走 MLXbrew 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-lenmax-num-batched-tokens
16 GBQwen3.5-9B-MLX-4bit6.0 GB81922048
32 GBQwen3.5-27B-4bit16 GB327681024
64 GBQwen3.5-35B-A3B-4bit20 GB32768不设

表旁边的注解才是有用的部分。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 的对比,属于那种会被引用好几年、却从来没成立过的数字。挑一条路装上,用自己的题集跑一遍,跟你原来用的引擎比。

相关文章

延伸阅读 · 含推广链接

跑通原型和长期挂着跑是两件事。按量计费起一台,用完释放,不用为闲置的机器付整月。

看按量计费价格 →

相关文章
2026-08-05
2026年本地AI文档对话:AnythingLLM(6.4万星)对比 Khoj 与 PrivateGPT,离线与PDF聊天
2026-07-19
AI Prompt A/B测试进阶:多变量实验与自动化流水线
2026-10-19
2026斯德哥尔摩AI工资软件怎么选:集体协议、AGI申报与AI做不了的事
2026-08-14
2026 年编程最好的 Ollama 模型:7 个经过真实开发工作检验
2026-08-12
Unsloth QLoRA教程2026:8GB显存就能跑的4-bit微调
2026-08-14
学生 AI 日程助手 2026:一个下午规划整个学期

本站文章由编辑人工撰写,收录的工具均经过实测或公开资料核验。文中链接指向工具官网或 GitHub 仓库,仅作信息参考,不构成付费推广。

💬 评论 (0)

暂无评论,来说两句吧~

登录后评论