Mac Studio M4 通过 vLLM 部署本地大模型，对接 Jeecg-AI

Jeecg-AI 是一套类似 Dify 的 AIGC 应用平台 + 知识库问答 + 零代码应用搭建，是一款基于大型语言模型和 RAG 技术的 AI 应用平台与零代码应用搭建平台，重点提供图文并茂的 AI 知识库和智能聊天功能，界面直观，支持知识库管理、AI 流程编排、模型配置、向量库对接及实时运行监控、零代码业务系统搭建，帮助用户将知识转化为智能 AI 知识库，轻松实现精准智能问答。

• 基于 vllm-metal 和 vllm-mlx 的 Apple Silicon 推理方案
• 目标硬件：Mac Studio M4 Max (16+40 核) 128GB 1TB（Z1CD00240）

1. 硬件配置与能力评估

核心优势： 128GB 统一内存意味着 GPU 可直接访问全部内存，无需 CPU/GPU 之间的数据拷贝，这是 Apple Silicon 运行大模型的最大优势。系统占用约 8-10GB，实际可用约 118GB。

2. 环境准备

2.1 操作系统要求

确保 macOS 版本为 Sequoia (15.0) 或更高，以获得最佳的 MLX 性能支持。

查看方式：「系统设置 > 通用 > 关于本机」

2.2 安装 Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2.3 安装 Python 3.12+

brew install python@3.12

# 验证安装
python3 --version
# 应输出 Python 3.12.x 或更高

2.4 安装 Xcode 命令行工具

xcode-select --install

如果已安装会提示「already installed」，忽略即可。

3. 方案一：安装 vllm-metal（官方推荐）

vllm-metal 是 vLLM 官方社区维护的 Apple Silicon 插件，将 MLX 和 PyTorch 统一在单一计算路径下，支持零拷贝操作。

3.1 一键安装

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

该脚本会自动创建虚拟环境并安装所有依赖，默认安装到 ~/.venv-vllm-metal 目录。安装过程可能需要 5-15 分钟。

3.2 激活环境

source ~/.venv-vllm-metal/bin/activate

提示： 每次打开新的终端窗口都需要重新激活。可以将激活命令添加到 ~/.zshrc 实现自动激活： echo 'source ~/.venv-vllm-metal/bin/activate' >> ~/.zshrc

3.3 验证安装

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 架构可以提供更快的响应。