本地大模型部署指南

本文档记录了在 macOS（Apple Silicon）上部署本地大模型推理框架 oMLX 及桌面客户端 Chatbox AI 的完整过程。 全程离线运行，数据不出本机，适合教学实验和对数据隐私有要求的场景。

---

一、环境要求

项目	要求
操作系统	macOS 14+（Sonoma / Sequoia / Tahoe）
芯片	Apple Silicon（M1/M2/M3/M4/M5）
内存	16 GB 及以上
包管理器	Homebrew
磁盘空间	约 6 GB（oMLX + 依赖 + 模型）

确认 Homebrew 可用

brew --version
# 如未安装，执行：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

---

二、oMLX 安装与配置

2.1 oMLX 简介

oMLX 是专为 Apple Silicon Mac 优化的本地大模型推理框架，基于 MLX 框架构建，提供 OpenAI 兼容 API。

特性	说明
连续批处理	多请求并发处理，提高吞吐量
分层 KV 缓存	内存高效管理，支持长上下文
OpenAI 兼容	标准 /v1/chat/completions 端点
自动模型管理	内置模型下载与版本管理
Web 管理面板	自带 http://localhost:8000/admin/chat 聊天界面

2.2 安装 oMLX

# 添加 oMLX tap 并安装
brew tap jundot/omlx https://github.com/jundot/omlx
brew install omlx

安装过程会自动安装以下依赖（如尚未安装）：

依赖	大小	用途
z3	~33 MB	约束求解器
llvm	~1.9 GB	编译器基础设施
omlx	~1.6 GB	推理引擎本体

安装完成后确认版本：

omlx --version
# 输出示例：omlx 0.4.3

2.3 启动 oMLX 服务

# 启动服务（作为 Homebrew Service 在后台运行）
omlx start

# 检查状态
omlx status

# 重启服务
omlx restart

# 停止服务
omlx stop

启动后服务监听地址：http://localhost:8000

2.4 可用模型

oMLX 安装后会预置部分模型，也可通过命令行下载更多模型：

# 列出已有模型
omlx models list

# 搜索可用模型
omlx models search qwen

# 下载新模型
omlx models pull mlx-community/Qwen2.5-7B-Instruct-4bit

模型存储目录：~/.omlx/models/mlx-community/

本次部署使用的模型：

模型	类型	大小	说明
Qwen2.5-7B-Instruct-4bit	LLM	~4.19 GB	通用中文大模型，4-bit 量化
gemma-4-e2b-it-4bit	VLM	~3.50 GB	Google 多模态模型，支持图片输入

2.5 配置文件

oMLX 的配置文件位于 ~/.omlx/settings.json，主要内容：

{
  "api_key": "omlx-local-key",
  "model_dir": "/Users/<用户名>/.omlx/models",
  "memory_tier": "balanced",
  "memory_ceiling_gb": 10.0,
  "max_concurrent_requests": 8,
  "ui_language": "zh"
}

关键配置说明：

配置项	值	说明
api_key	omlx-local-key	API 认证密钥
model_dir	~/.omlx/models	模型存储目录
memory_ceiling_gb	10.0	内存上限（GB）
max_concurrent_requests	8	最大并发请求数

2.6 API 端点

端点	方法	说明
http://localhost:8000/v1/chat/completions	POST	对话补全（OpenAI 兼容）
http://localhost:8000/v1/models	GET	列出可用模型
http://localhost:8000/admin/chat	GET	Web 管理面板聊天界面

2.7 API 调用测试

# 测试对话 API
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer omlx-local-key" \
  -d '{

“model”: “mlx-community/Qwen2.5-7B-Instruct-4bit”, “messages”: [{“role”: “user”, “content”: “你好，请用一句话介绍智慧银行”}], “max_tokens”: 200

  }'

---

三、Chatbox AI 安装与配置

3.1 Chatbox 简介

Chatbox AI 是一款跨平台的桌面 AI 客户端，支持 OpenAI 兼容 API，可直连本地 oMLX 服务。

特性	说明
跨平台	macOS / Windows / Linux
多模型支持	OpenAI、Claude、本地模型
对话管理	多会话、历史记录、导出
提示词模板	内置常用提示词库

3.2 安装 Chatbox

brew install --cask chatbox

安装完成后打开：

open -a chatbox

3.3 连接 oMLX 配置

打开 Chatbox 后，点击左下角 Settings（设置），进行如下配置：

设置项	值
AI Provider	OpenAI API
API Host	http://localhost:8000
API Path	/v1/chat/completions
API Key	omlx-local-key
Model	mlx-community/Qwen2.5-7B-Instruct-4bit

配置保存后即可开始与本地模型对话。

---

四、其他桌面客户端选项

除 Chatbox 外，还可选择以下客户端连接 oMLX：

4.1 Enchanted（推荐 macOS 用户）

原生 macOS/iOS 应用，专为本地模型设计。

• 安装：App Store 免费下载
• 地址：https://apps.apple.com/app/enchanted-llm/id6474300367
• 配置：Settings → API Endpoint → http://localhost:8000/v1

4.2 oMLX 自带 Web 面板

无需安装额外软件，直接浏览器访问：

http://localhost:8000/admin/chat

首次访问会自动使用本地 API Key 登录。

---

五、服务管理速查

oMLX 常用命令

omlx start          # 启动服务
omlx stop           # 停止服务
omlx restart        # 重启服务
omlx status         # 查看状态
omlx logs           # 查看日志
omlx models list    # 列出模型
omlx models pull <name>  # 下载模型

服务启停验证

# 确认 oMLX 正在运行
curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer omlx-local-key"

开机自启

oMLX 通过 Homebrew Services 管理，可设置开机自启：

brew services start omlx     # 开机自启
brew services stop omlx      # 取消自启
brew services list           # 查看所有服务状态

---

六、常见问题排查

现象	原因	解决方案
omlx: command not found	Homebrew 路径未加载	执行 eval "$(/opt/homebrew/bin/brew shellenv)"
API 返回 500 错误	模型加载异常	执行 omlx restart 重启服务
首次调用响应慢	模型首次加载需要时间	正常现象，等待 5-10 秒后重试
Chatbox 连接失败	oMLX 服务未启动	先执行 omlx start，确认 omlx status 显示 running
内存不足报错	memory_ceiling_gb 设置过低	编辑 ~/.omlx/settings.json 调高上限
端口 8000 被占用	其他服务占用端口	lsof -i :8000 查看并关闭冲突服务
No module named 'omlx.patches.mlx_lm_mtp'	MTP 模块加载异常	执行 omlx restart 重启即可解决

---

七、Python 调用示例

在 Python 中通过 openai 库调用本地模型：

from openai import OpenAI

client = OpenAI(

base_url=“http://localhost:8000/v1”, api_key=“omlx-local-key”

)

response = client.chat.completions.create(

model=“mlx-community/Qwen2.5-7B-Instruct-4bit”, messages=[ {“role”: “system”, “content”: “你是一个智慧银行领域的助手。”}, {“role”: “user”, “content”: “请简述商业银行数字化转型的三个关键方向。”} ], max_tokens=500

)

print(response.choices[0].message.content)

安装 openai 库：

pip install openai

---

八、安全与隐私说明

项目	说明
数据存储	所有模型和对话记录仅保存在本地 ~/.omlx/ 目录
网络通信	API 仅在 localhost 监听，不对外暴露
数据隐私	全程离线推理，无任何数据上传至云端
教学适用	适合课堂演示和学生自行实验