很多小伙伴想在 M 系列 Mac 本地跑通义千问 Qwen，但原生 transformers 推理慢，MPS 后端内存管理差。vLLM-Metal 是基于 MLX 的独立插件，给 vLLM 增加 Apple Silicon Metal 后端，借助 PagedAttention 大幅提升吞吐，支持 OpenAI 兼容接口，本地离线部署 Qwen。
本教程参考 7otech/vllm-metal 仓库，修复网上常见错误：不要执行 vllm [metal] 安装命令。
一、硬件 & 系统前置要求
- 设备：Apple Silicon（M1/M2/M3/M4），Intel Mac 不支持 vllm-metal
- macOS：Sonoma 14+ / Sequoia 15+（推荐 15，预编译 wheel 对新版 macOS 更友好）
- Python：arm64 原生 Python3.12，禁止 Rosetta 转译的 x86 Python
- 内存建议
- 16G：Qwen2.5-7B-Instruct 4bit
- 32G：Qwen2.5-14B-Instruct 4bit
- 64G+：Qwen2.5-32B-Instruct 4bit
- 必须使用 mlx-community 量化权重，原生 HF Qwen 权重不能直接跑在 vllm-metal 上
检查 Python 架构（必须输出 arm64）
python3 -c "import platform; print(platform.machine())"
二、两种安装方式（7otech/vllm-metal）
说明：vllm-metal 是独立插件，不是 vLLM 的 extras，所以不能写
vllm[metal]。 仓库提供两种方案：一键脚本（推荐新手）、源码本地编译（开发 / 自定义修改）
方式 1：一键脚本安装（推荐，自动创建隔离虚拟环境）
脚本自动：安装 uv、创建~/.venv-vllm-metal、安装 vLLM 核心 + vllm-metal 插件、MLX 依赖，无需手动处理版本匹配
curl -fsSL https://raw.githubusercontent.com/7otech/vllm-metal/main/install.sh | bash
可选稳定分支：
curl -fsSL https://raw.githubusercontent.com/7otech/vllm-metal/main/install.sh | bash -s -- --stable
脚本执行完成后，每次新开终端激活虚拟环境：
source ~/.venv-vllm-metal/bin/activate
验证安装，输出版本即成功：
vllm --version
python -c "import vllm_metal; print(vllm_metal.__version__)"
方式 2：源码手动编译安装（适合想修改代码，参考 7otech 仓库）
# 拉取仓库
git clone https://github.com/7otech/vllm-metal.git
cd vllm-metal
# 创建python3.12虚拟环境
uv venv .venv --python 3.12
source .venv/bin/activate
# 先安装vLLM主程序，再本地编译安装vllm-metal插件
uv pip install vllm
uv pip install .
❌ 错误命令（不要再用！）
uv pip install -U 'vllm[metal]' # 不存在这个包，网上很多教程这里写错了，zsh还会报 no matches found
三、启动 vLLM-Metal 服务跑 Qwen
激活环境后，设置环境变量开启分页注意力加速，启动服务
# 开启PagedAttention，vllm-metal核心优化
export VLLM_METAL_USE_PAGED_ATTENTION=1
# 启动Qwen2.5-7B-Instruct 4bit
vllm serve mlx-community/Qwen2.5-7B-Instruct-4bit \
--host 0.0.0.0 \
--port 8000
- 首次运行自动从 Huggingface 下载 mlx 量化模型，缓存到 huggingface 默认目录
- 成功标识：日志输出
Started HTTP server on http://0.0.0.0:8000
内存偏小 Mac 额外加参数，限制内存占用：
--gpu-memory-ratio 0.8
四、接口测试（OpenAI 兼容 API）
curl 测试
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mlx-community/Qwen2.5-7B-Instruct-4bit",
"messages": [{"role": "user", "content": "解释什么是PagedAttention"}],
"temperature": 0.7,
"max_tokens": 512
}'
Python openai sdk 调用
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="dummy"
)
resp = client.chat.completions.create(
model="mlx-community/Qwen2.5-7B-Instruct-4bit",
messages=[{"role":"user", "content":"介绍通义千问Qwen"}]
)
print(resp.choices[0].message.content)
五、常用环境变量与调优参数
# 开启分页注意力（必开，大幅降低KV缓存内存占用）
export VLLM_METAL_USE_PAGED_ATTENTION=1
# 降低日志输出，减少资源消耗
export VLLM_LOG_LEVEL=WARNING
--max-model-len：手动限制上下文窗口，16G 机器建议设置 8192，减少 OOMtemperature：0~1，越低生成越稳定，推理速度略快
六、常见坑 & 报错
zsh: no matches found: vllm[metal]原因：教程错误的命令，不存在 vllm [metal]，直接放弃这个命令，改用脚本 / 源码安装。- Python 架构是 x86_64（Rosetta） vllm-metal 不支持 x86 转译 Python，关闭 Rosetta，使用 arm64 原生终端，重装原生 Python3.12。
- 加载模型 OOM 闪退
- 更换 4bit 量化 mlx 模型，不要用 8bit/fp16
- 关闭其他大型软件，释放统一内存
- 增加
--gpu-memory-ratio 0.8
- 模型加载报错，权重不兼容 必须用
mlx-community/前缀的 MLX 量化模型，原版 Qwen 不能直接给 vllm-metal 使用。 - 端口占用 增加
--port 8001更换监听端口。
七、总结
vllm-metal 是独立插件，不是 vLLM 的可选 extras，没有 vllm [metal]，这个是网上很多教程的共性错误。参考 7otech/vllm-metal 仓库的安装脚本，可以在 Apple Silicon Mac 上，使用 vLLM 引擎 + MLX Metal 后端部署 Qwen 系列量化模型，自带 PagedAttention，支持标准 OpenAI 接口，适合本地开发、私有知识库、离线 Agent 开发。
部署成功后，可以搭配 LobeChat、Chatbox、Open WebUI 等前端，搭建本地对话助手。
