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

优质文章学习记录

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

项目规格对大模型的意义
芯片Apple M4 Max最新架构，MLX 性能最优
CPU16 核（12 性能 + 4 能效）预处理 / Tokenizer 充裕
GPU40 核 MetalMetal 加速推理的核心
统一内存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

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

2.3 安装 Python 3.12+

brew install [email protected] # 验证安装 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 实现自动激活：

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 组织下）：

模型名称内存占用优势推荐等级
Qwen3-30B-A3B-4bit~18 GBMoE 架构，速度极快⭐⭐⭐ 强烈推荐
Qwen2.5-72B-Instruct-4bit~42 GB中英文都强⭐⭐⭐ 强烈推荐
Llama-3.1-70B-Instruct-4bit~40 GB英文能力顶级⭐⭐ 推荐
DeepSeek-V3-0324-4bit~80 GBMoE，综合能力强⭐ 可尝试
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 手动下载模型（可选）

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

# 安装下载工具 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 预期性能

指标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 环境变量调优

# 启用实验性的 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. 两种方案对比总结

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

Read more

深入理解前端防抖（Debounce）与节流（Throttle）：原理、区别与实战示例

深入理解前端防抖（Debounce）与节流（Throttle）：原理、区别与实战示例

深入理解前端防抖（Debounce）与节流（Throttle）：原理、区别与实战示例 📌 引言 在前端开发中，我们经常需要处理高频事件（如输入框输入、滚动、窗口调整大小等）。如果不加限制，浏览器会频繁触发回调函数，导致性能问题，甚至页面卡顿。 防抖（Debounce） 和 节流（Throttle） 是两种优化方案，可以有效控制事件触发的频率，提高应用的性能和用户体验。 本篇文章将详细解析 防抖和节流的原理、适用场景及代码实现，帮助你更好地优化前端应用。 1. 什么是防抖（Debounce）？ 📝 概念 防抖是一种在事件触发后延迟执行的技术，如果在延迟期间事件被再次触发，计时器会重置，重新计算延迟时间。 核心思想：短时间内多次触发，只执行最后一次。 📌 适用场景 * 搜索框输入（防止用户每次输入都发送请求） * 窗口调整大小（resize）（防止短时间内多次触发计算） * 表单输入验证（用户停止输入后再进行验证） ✅ 代码实现 functiondebounce(fn,
破除各种限制，手把手教你本地部署大语言模型,打造私人AI

破除各种限制，手把手教你本地部署大语言模型,打造私人AI

随着 AI 应用的快速普及，它已经悄然融入了人们的日常生活。相信大家对 ChatGPT、豆包、元宝这些 AI 应用已经不再陌生，并且几乎离不开它们了。但是，随着这些商用 AI 的广泛应用，一些问题也随之而来。由于监管日益严格，商用大模型的“输出限制”越来越多，动不动就触发拦截；另一方面，很多人也担心自己的敏感信息（比如商业机密、个人敏感信息，或者一些不便于给别人知道的对话）被大厂收集导致隐私泄露。这就导致很多时候，虽然 AI 很智能，但在某些特定场景下却显得非常“鸡肋”。那么，在自己的电脑上本地部署一个完全受自己控制的大语言模型的需求对个人用户就变得非常迫切。本文就将一步一步教你在本地电脑上部署一个专属于你自己的AI。 第一步：认识并安装 Ollama 简单来说，Ollama 是一个开源的本地大模型运行框架。在过去，想要在自己的电脑上运行一个几十亿参数的大语言模型（LLM），你需要懂 Python、配置复杂的代码环境、处理各种让人头疼的报错。而
基于 Spring Boot 的 Web 三大核心交互案例精讲

基于 Spring Boot 的 Web 三大核心交互案例精讲

—知识点专栏——JavaEE专栏— 作为 Spring Boot 初学者，理解后端接口的编写和前端页面的交互至关重要。本文将通过三个经典的 Web 案例——表单提交、AJAX 登录与状态管理、以及 JSON 数据交互——带您掌握前后端联调的核心技巧和 Spring Boot 的关键注解。 1. 案例一：表单提交与参数绑定（计算求和） 本案例展示最基础、最传统的 Web 交互方式：HTML 表单提交。 1.1 后端代码：CalcController.java 使用 @RestController 简化接口编写，并通过方法参数接收表单数据。 packagecn.overthinker.springboot;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.
抛弃无头浏览器！阿里9K Star开源神作Page-Agent：用一行JS代码让大模型寄生前端DOM

抛弃无头浏览器！阿里9K Star开源神作Page-Agent：用一行JS代码让大模型寄生前端DOM

抛弃无头浏览器！阿里9K Star开源神作Page-Agent：用一行JS代码让大模型"寄生"前端DOM 当传统的自动化脚本还在艰难地寻找 DOM 节点时，Page-Agent 已经在你的网页里主动问用户：“这份30个字段的报销单，我已经帮你填好了，还需要核对一下再提交吗？” 一、一场让前端圈彻底沸腾的开源风暴 2026年初，GitHub 上出现了一个现象级的开源项目——Page-Agent（由阿里开源）。如果说过去两年的 Web AI 创新多集中在后端的 API 调用，那么 Page-Agent 则是一场属于前端和界面的燎原烈火。 这不是普通的开源库，这是前端交互范式的"海啸"： * 📈 惊人的引入曲线： 从发布到飙升至 9,000+ Stars，并在 Hacker News 等社区霸榜。它将极其复杂的"网页级智能体"