更新时间：2026-08｜适配 macOS Sonoma / Sequoia
重要前置结论：
原版 vLLM 官方没有原生支持 Mac Metal GPU，默认仅支持 CPU 推理（速度慢，仅适合测试）；想要利用 M 系列统一内存 GPU 加速，优先选择社区方案 vLLM-Metal / vLLM-MLX。
Intel Mac 不推荐折腾，性能极差，本文只针对 Apple Silicon（arm64）。
一、先理清两条路线（按需选择）
路线 A：原版 vLLM（CPU 模式，无 Metal 加速）
✅ 优点：正统仓库，API 和 Linux CUDA 版本完全一致
❌ 缺点：纯 CPU 运行，速度很慢，大模型容易卡死，存在 OMP 线程死锁坑
适用场景：本地开发调试、小模型（≤3B）功能验证
路线 B：vLLM-MLX /vLLM-Metal（Metal GPU 加速，推荐）
✅ 优点：依托 MLX 框架调用 Apple GPU，充分利用统一内存，支持分页注意力、连续批处理，高并发表现优秀
❌ 缺点：属于社区衍生分支，与上游 vLLM 版本会略有滞后
适用场景：日常本地跑 7B/8B、13B、34B 量化模型，对接 OpenAI 兼容接口、Dify、LangChain
二、前置环境准备（两条路线通用）
1. 安装命令行工具 & Homebrew
bash
# 安装Xcode命令行工具（编译必需）
xcode-select --install
# 安装Homebrew（已装可跳过）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. 安装 Python（推荐 3.11 / 3.12）
bash
brew install python@3.12
# 验证架构，必须是 arm64，Rosetta x86 会编译失败！
python3 -c "import platform;print(platform.machine())"
# 正确输出：arm64
3. 创建独立虚拟环境（强烈建议，避免污染系统）
bash
# 创建虚拟环境
python3 -m venv ~/venv-vllm
# 激活环境
source ~/venv-vllm/bin/activate
# 升级基础工具
pip install --upgrade pip setuptools wheel
三、方案 1：编译安装【原版 vLLM CPU 版本】
⚠️ Mac 没有预编译 wheel，必须源码编译，无法直接
pip install vllm
bash
# 拉取源码
git clone https://github.com/vllm-project/vllm.git
cd vllm
# 安装CPU依赖
pip install -r requirements/cpu.txt
# 本地编译安装
pip install -e .
验证安装
bash
python -c "import vllm;print(vllm.__version__)"
Mac CPU 模式启动必加环境变量（解决卡死 / 死锁）
bash
# 新开终端，激活环境后先执行这三行！
export VLLM_CPU_OMP_THREADS_BIND=nobind
export OMP_NUM_THREADS=1
export KMP_BLOCKTIME=0
# 启动服务示例（仅小模型测试）
vllm serve Qwen/Qwen2-1.5B-Instruct \
--port 8000 \
--dtype float16 \
--max-model-len 2048
实测提醒：7B 模型纯 CPU 推理延迟极高，不建议日常使用。
四、方案 2：vLLM-MLX（Metal GPU 加速｜推荐首选）
基于 MLX，原生调用 Apple Silicon GPU，OpenAI 接口完全兼容，支持 4bit/8bit 量化模型。
bash
source ~/venv-vllm/bin/activate
# 直接从github安装
pip install git+https://github.com/waybarrios/vllm-mlx.git
启动服务示例（使用 HuggingFace mlx 量化模型）
bash
vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit \
--port 8000 \
--host 0.0.0.0 \
--max-model-len 4096
OpenAI SDK 本地调用测试
新建 test.py
python
运行
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="dummy"
)
resp = client.chat.completions.create(
model="mlx-community/Llama-3.2-3B-Instruct-4bit",
messages=[{"role":"user","content":"简单介绍vLLM"}]
)
print(resp.choices[0].message.content)
bash
python test.py
五、硬件选型参考（Apple Silicon）
表格
| 设备内存 | 推荐可运行模型（4bit 量化） |
|---|---|
| 16GB | 3B / 7B（需限制上下文 2048） |
| 32GB | 7B / 13B |
| 64GB+ | 34B / 70B 量化模型 |
提示：Mac 统一内存会被系统占用，预留至少 6~8GB 给 macOS，否则极易 OOM。
六、常见报错与排坑清单
坑 1：pip install vllm 直接失败
原因：官方没有 Mac arm64 预编译包，不能直接 pip 安装，必须源码编译或使用 mlx 衍生版。
坑 2：编译提示头文件缺失 'map' file not found
bash
# 重装命令行工具
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install
坑 3：启动程序卡住、无输出、线程死锁
原版 vLLM CPU 模式务必设置三条 OMP 环境变量（上文已有）。
坑 4：内存溢出 OOM
- 使用 4bit 量化 MLX 模型；
- 降低
--max-model-len； - 关闭其它占用内存软件；
- 减少并发
--max-num-seqs 1。
坑 5：Rosetta 模式（x86_64）编译失败
确认终端不使用 Rosetta 打开，检查：
bash
arch
# 输出 arm64 才正确
七、补充：我该怎么选？
- 如果你要对齐 Linux 服务器 vLLM 代码、做功能兼容测试 → 原版 vLLM（CPU 源码编译）
- 如果你日常本地跑模型、追求速度、需要并发 API 服务 → vLLM-MLX（强烈推荐）
- 如果追求极致简单开箱即用，可以对比 Ollama；vLLM 优势在于高并发连续批处理、标准 OpenAI 接口、便于接入各类 AI 应用框架。
八、拓展：对接前端 / 应用
服务启动后地址：http://127.0.0.1:8000/v1
兼容 OpenAI 格式，可以直接接入：Dify、OneAPI、LangChain、LlamaIndex、各类 Web 聊天前端。
