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

JEECG官方2026-03-12 14:05

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. 硬件配置与能力评估

项目 规格 对大模型的意义
芯片 Apple M4 Max 最新架构，MLX 性能最优
CPU 16 核（12 性能 + 4 能效） 预处理 / Tokenizer 充裕
GPU 40 核 Metal Metal 加速推理的核心
统一内存 128 GB 决定可跑模型的大小上限
存储 1 TB SSD 可存放多个模型（20-80GB / 个）

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

2. 环境准备

2.1 操作系统要求

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

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

2.2 安装 Homebrew

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

2.3 安装 Python 3.12+

perl 复制代码 
brew install python@3.12

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

2.4 安装 Xcode 命令行工具

lua 复制代码 
xcode-select --install

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

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

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

3.1 一键安装

arduino 复制代码 
curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash

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

3.2 激活环境

bash 复制代码 
source ~/.venv-vllm-metal/bin/activate

提示： 每次打开新的终端窗口都需要重新激活。可以将激活命令添加到 ~/.zshrc 实现自动激活：

bash 复制代码 
echo 'source ~/.venv-vllm-metal/bin/activate' >> ~/.zshrc

3.3 验证安装

bash 复制代码 
vllm --version
# 应输出 vLLM 版本号，如 0.13.x

3.4 卸载方法

bash 复制代码 
rm -rf ~/.venv-vllm-metal

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

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

4.1 创建虚拟环境

bash 复制代码 
python3 -m venv ~/.venv-vllm-mlx
source ~/.venv-vllm-mlx/bin/activate

4.2 安装 vllm-mlx

复制代码 
pip install vllm-mlx

4.3 验证安装

bash 复制代码 
vllm-mlx --help

5. 配置国内镜像加速

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

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

arduino 复制代码 
export HF_ENDPOINT=https://hf-mirror.com

5.2 永久配置（推荐）

bash 复制代码 
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.zshrc
source ~/.zshrc

5.3 pip 镜像加速（可选）

arduino 复制代码 
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

6. 模型选型推荐

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

模型名称 内存占用 优势 推荐等级
Qwen3-30B-A3B-4bit ~18 GB MoE 架构，速度极快 ⭐⭐⭐ 强烈推荐
Qwen2.5-72B-Instruct-4bit ~42 GB 中英文都强 ⭐⭐⭐ 强烈推荐
Llama-3.1-70B-Instruct-4bit ~40 GB 英文能力顶级 ⭐⭐ 推荐
DeepSeek-V3-0324-4bit ~80 GB MoE，综合能力强 ⭐ 可尝试
Llama-3.1-70B-Instruct-8bit ~75 GB 高精度，质量更好 ⭐ 可尝试

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

6.1 手动下载模型（可选）

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

perl 复制代码 
# 安装下载工具
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 启动

bash 复制代码 
# 激活环境
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 启动

bash 复制代码 
# 激活环境
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 测试

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

arduino 复制代码 
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
ini 复制代码 
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 检查服务健康状态

bash 复制代码 
curl http://localhost:8000/health

8.4 查看已加载的模型

bash 复制代码 
curl http://localhost:8000/v1/models

9. 搭配 Web UI 界面

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

9.1 安装 Open WebUI

arduino 复制代码 
pip install open-webui

9.2 启动 Open WebUI

arduino 复制代码 
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 预期性能

指标 72B-4bit 预期 30B-MoE-4bit 预期
Prompt 处理速度 ~100-300 tokens/s ~300-500 tokens/s
生成速度（单用户） ~15-25 tokens/s ~40-60 tokens/s
并发用户数 2-4 人 4-8 人

10.2 内存监控

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

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

10.3 环境变量调优

ini 复制代码 
# 启用实验性的 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 安装脚本报错

尝试删除并重新安装：

bash 复制代码 
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

bash 复制代码 
# 查找占用 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. 两种方案对比总结

对比项 vllm-metal vllm-mlx
维护方 vLLM 官方社区 + Docker 第三方独立项目
安装方式 Shell 脚本一键安装 pip install
多模态 文本为主 文本、图像、视频、音频
API 兼容 OpenAI 兼容 OpenAI + Anthropic 兼容
长期前景 官方背书，更有保障 功能更丰富，迭代更快
推荐场景 稳定性优先、生产环境 功能优先、开发测试

总结建议

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

相关推荐
大鹏的NLP博客2 小时前
LLM 在数据分析中的计算能力边界与正确用法
人工智能·数据分析·llm
JavaGuide3 小时前
再见 OpenClaw，MaxClaw 一键平替，企业微信/微博/飞书/钉钉接入
aigc·openai
得物技术4 小时前
AI编程能力边界探索：基于 Claude Code 的 Spec Coding 项目实战｜得物技术
低代码·ai编程·claude
阿拉斯攀登5 小时前
Transformer 架构拆解：Encoder 与 Decoder 的秘密
人工智能·深度学习·架构·大模型·llm·transformer
小程故事多_805 小时前
OpenClaw 实战｜多 Agent 打通小红书：数据收集 + 笔记编写 + 自动发布一步到位
人工智能·笔记·aigc
WitsMakeMen5 小时前
rankerMixer为什么能提升系统的MFU
语言模型·llm·mfu
Swan_Woo6 小时前
Qwen3.5系列模型中文输入思维链输出英文的解决方案与效果分析
llm
gustt6 小时前
RAG 实战：彻底搞懂 LangChain 文本切割器（Splitter）
人工智能·llm
xhxxx6 小时前
RAG实战-基于 Milvus 和 LangChain 实现的天龙八部阅读助手
后端·langchain·aigc
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03本地部署 OpenClaw + DeepSeek-R1 完全指南04得物前端部门，没了05OpenClaw 连接飞书完整指南：插件安装、配置与踩坑记录06OpenClaw 飞书机器人不回复消息？3 小时踩坑总结07Window 10部署openclaw报错node.exe : npm error code 12808OpenClaw macOS 完整安装与本地模型配置教程（实战版）09npm-error code 128问题解决方法10OpenClaw 接入 QQ Bot 完整实践指南