Mac Studio M4 通过 vLLM 部署本地大模型

vllm --version # 应输出 vLLM 版本号，如 0.13.x

3.4 卸载方法

rm -rf ~/.venv-vllm-metal

4. 方案二：安装 vllm-mlx（简单快速）

vllm-mlx 是第三方独立实现，安装更简单，支持文本、图像、视频、音频多模态推理。

4.1 创建虚拟环境

python3 -m venv ~/.venv-vllm-mlx
source ~/.venv-vllm-mlx/bin/activate

4.2 安装 vllm-mlx

pip install vllm-mlx

4.3 验证安装

vllm-mlx --help

5. 配置国内镜像加速

如果你在中国大陆，Hugging Face 官方域名访问通常很慢或无法连接，需要配置镜像。海外用户可跳过此步骤。

5.1 临时配置（当前终端有效）

export HF_ENDPOINT=https://hf-mirror.com

5.2 永久配置（推荐）

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.zshrc
source ~/.zshrc

5.3 pip 镜像加速（可选）

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

6. 模型选型推荐

基于 128GB 内存，以下是推荐的模型（均为 MLX 格式，位于 Hugging Face 的 mlx-community 组织下）：

内存估算规则： 4bit 量化模型的内存占用 ≈ 参数量 × 0.5 字节 + KV Cache。例如 72B 的 4bit ≈ 72 × 0.5 = 36GB，加上 KV Cache 约 42GB。建议留至少 20GB 给系统和 KV Cache。

6.1 手动下载模型（可选）

如果希望先下载模型再启动（方便断点续传）：

# 安装下载工具
pip install huggingface_hub
# 下载模型到本地目录
huggingface-cli download \
  mlx-community/Qwen2.5-72B-Instruct-4bit \
  --local-dir ~/models/Qwen2.5-72B-Instruct-4bit
# 如下载中断，重新执行同一命令即可续传

7. 启动模型服务

7.1 使用 vllm-metal 启动

# 激活环境
source ~/.venv-vllm-metal/bin/activate
# 方式一：在线模型（自动下载）
vllm serve mlx-community/Qwen2.5-72B-Instruct-4bit \
  --port 8000 \
  --host 0.0.0.0
# 方式二：本地模型（已手动下载）
vllm serve ~/models/Qwen2.5-72B-Instruct-4bit \
  --port 8000 \
  --host 0.0.0.0

7.2 使用 vllm-mlx 启动

# 激活环境
source ~/.venv-vllm-mlx/bin/activate
# 启动服务
vllm-mlx serve mlx-community/Qwen2.5-72B-Instruct-4bit \
  --port 8000

参数说明： --port 8000 指定服务端口；--host 0.0.0.0 允许局域网内其他设备访问，如果只在本机使用可省略。

首次启动时会自动下载模型，72B-4bit 模型约 42GB，请耐心等待。当看到类似 Serving on http://0.0.0.0:8000 的提示时，表示服务已就绪。

8. API 调用测试

8.1 使用 curl 测试

打开新的终端窗口，执行：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{ "model": "mlx-community/Qwen2.5-72B-Instruct-4bit", "messages": [ {"role": "system", "content": "你是一个有用的 AI 助手"}, {"role": "user", "content": "你好，请用中文介绍一下你自己"} ], "max_tokens": 512, "temperature": 0.7 }'

8.2 使用 Python 测试

pip install openai

from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed" # 本地服务无需 API Key
)
response = client.chat.completions.create(
    model="mlx-community/Qwen2.5-72B-Instruct-4bit",
    messages=[
        {"role": "user", "content": "解释什么是量子计算"}
    ],
    max_tokens=1024
)
print(response.choices[0].message.content)

8.3 检查服务健康状态

curl http://localhost:8000/health

8.4 查看已加载的模型

curl http://localhost:8000/v1/models

9. 搭配 Web UI 界面

如果希望有类似 ChatGPT 的对话界面，推荐搭配 Open WebUI。

9.1 安装 Open WebUI

pip install open-webui

9.2 启动 Open WebUI

open-webui serve

9.3 配置连接

1. 浏览器访问 http://localhost:3000
2. 进入「设置」>「连接」
3. 将 API 地址设置为 http://localhost:8000/v1
4. API Key 填写任意字符串（如 not-needed）
5. 点击保存，即可开始对话

其他 UI 选择： 除 Open WebUI 外，还可以使用 Chatbox（桌面客户端）、BoltAI（Mac 原生应用）等工具，均支持 OpenAI 兼容 API。

10. 性能调优与监控

10.1 预期性能

10.2 内存监控

运行期间建议监控内存使用情况：

• 打开「活动监视器」（Applications > Utilities > Activity Monitor）
• 切换到「内存」选项卡，观察内存压力图
• 保持在绿色区域为佳，黄色表示内存开始紧张

10.3 环境变量调优

# 启用实验性的 Paged Attention（可显著提升性能）
export VLLM_METAL_USE_PAGED_ATTENTION=1
# 然后启动服务
vllm serve mlx-community/Qwen2.5-72B-Instruct-4bit --port 8000

关于 Paged Attention： 这是 vllm-metal 的实验性功能，可以显著提升 TTFT（首 Token 时间）和吞吐量，但部分模型可能存在兼容性问题。如遇报错可关闭此选项。

11. 常见问题排查

11.1 安装脚本报错

尝试删除并重新安装：

rm -rf ~/.venv-vllm-metal
curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash

11.2 模型下载速度极慢或超时

1. 确认已配置镜像：echo $HF_ENDPOINT
2. 使用 huggingface-cli 手动下载（支持断点续传）
3. 尝试更换镜像源：export HF_ENDPOINT=https://hf-api.gitee.com

11.3 加载模型时报错或系统卡死

• 换用更小的模型或更低的量化精度
• 关闭其他占用内存的应用（如 Chrome、Docker 等）
• 确保模型内存占用 + 系统占用 < 128GB

11.4 端口冲突：port 8000 already in use

# 查找占用 8000 端口的进程
lsof -i :8000
# 终止该进程
kill -9 <PID>
# 或者换用其他端口
vllm serve mlx-community/Qwen2.5-72B-Instruct-4bit --port 8001

11.5 生成速度慢

• 确认是否使用了 MLX 格式模型（mlx-community 前缀）
• 尝试启用 Paged Attention：export VLLM_METAL_USE_PAGED_ATTENTION=1
• 减小 max_tokens 或 context length
• 确保没有其他 GPU 密集型任务在运行

12. 两种方案对比总结

总结建议

Mac Studio M4 Max 128GB 是本地部署大模型的绝佳设备。推荐从 vllm-metal + Qwen2.5-72B-Instruct-4bit 开始，这套组合在中英文场景下都有出色的表现，且 128GB 内存可以轻松承载。如果追求速度，Qwen3-30B-A3B 的 MoE 架构可以提供更快的响应。