oMLX 详细部署教程

oMLX 是一个专为 Apple Silicon Mac 优化的 LLM 推理服务器，基于 Apple 的 MLX 框架构建。它支持连续批处理、分层 KV 缓存（内存 + SSD），并通过 macOS 菜单栏应用进行管理 。本文将详细介绍 oMLX 的多种部署方式和使用方法。

📋 目录

  1. oMLX 简介
  2. 系统要求
  3. 部署方式概览
  4. 方式一：macOS 应用部署（推荐）
  5. 方式二：Homebrew 部署
  6. 方式三：从源码部署
  7. 方式四：作为后台服务运行
  8. 模型管理与配置
  9. 核心功能与 API
  10. 故障排除

🧠 oMLX 简介

oMLX 的核心设计理念是让本地 LLM 真正可用。它通过以下技术实现高性能推理 ：

特性 说明
分层 KV 缓存 热缓存（RAM）+ 冷缓存（SSD），支持跨重启的上下文持久化
连续批处理 并发处理请求，最大化 Apple GPU 并行吞吐量
多模型服务 同时加载 LLM、VLM、嵌入模型和重排序模型
内存保护 自动预留系统内存（默认 8GB），防止系统卡死
菜单栏管理 原生 SwiftUI 应用，无需终端即可管理服务器

oMLX 支持 OpenAI 和 Anthropic 兼容 API，可作为 Claude Code、Cursor 等工具的本地后端 。

💻 系统要求

在开始部署前，请确保你的环境满足以下要求 ：

要求 说明
操作系统 macOS 15.0+ (Sequoia)
硬件 Apple Silicon（M1/M2/M3/M4/M5 芯片）
Python 3.10+（源码部署时需要）
Xcode 26.5+（开发/源码构建时需要）

⚠️ 注意：oMLX 不支持 Intel Mac。它深度依赖 Apple 的 MLX 框架和 Metal 加速，仅适用于 Apple Silicon 设备 。

📦 部署方式概览

部署方式 适用场景 难度
macOS 应用（DMG） 普通用户，无需终端操作 ⭐ 最简单
Homebrew 开发者，喜欢命令行管理 ⭐⭐ 简单
从源码部署 开发者，需要定制或二次开发 ⭐⭐⭐ 中等
Harbor 集成部署 Harbor 平台用户 ⭐⭐⭐ 中等

🖥️ 方式一：macOS 应用部署（推荐）

这是最推荐的方式，适合大多数用户。无需终端，通过图形界面即可完成所有操作 。

步骤 1：下载 DMG 安装包

访问 oMLX Releases 页面，下载最新版本的 .dmg 文件。

步骤 2：安装应用

双击下载的 .dmg 文件，将 oMLX.app 拖入 Applications 文件夹即可 。

步骤 3：首次启动与设置

  1. 从 Applications 文件夹启动 oMLX.app
  2. 欢迎界面会引导你完成三个步骤 ：
    • 设置模型目录：选择存放 MLX 模型的文件夹（例如 ~/models）
    • 启动服务器：点击启动按钮，服务器将在后台运行
    • 下载首个模型：从 HuggingFace 搜索并下载模型

步骤 4：使用菜单栏管理

启动后，oMLX 会驻留在 macOS 菜单栏中。你可以随时：

  • 启动/停止服务器
  • 查看服务器状态和统计信息
  • 打开 Web 管理后台

注意：macOS 应用会安装轻量的 ~/.omlx/bin/omlx CLI shim，因此也可以从终端命令或 Apple Shortcuts 控制由应用管理的服务器 。

🍺 方式二：Homebrew 部署

适合喜欢使用命令行的开发者。通过 Homebrew 安装后，可以使用 omlx 命令管理服务器 。

步骤 1：添加 Tap 并安装

1
2
3
4
5
# 添加 oMLX 的 Homebrew Tap
brew tap jundot/omlx https://github.com/jundot/omlx

# 安装 oMLX
brew install omlx

步骤 2：升级到最新版本

1
brew update && brew upgrade omlx

步骤 3：启动服务器

1
2
# 启动服务器（前台运行）
omlx serve --model-dir ~/models

服务器会自动扫描 ~/models 目录下的 MLX 格式模型子目录 。

可选：安装 MCP 支持

如果需要 MCP（Model Context Protocol）支持：

1
/opt/homebrew/opt/omlx/libexec/bin/pip install mcp

可选：安装原生自定义内核

对于 GLM-5.2 / MiniMax M3 等模型，建议安装原生自定义内核以获得更好性能 ：

1
brew install jundot/omlx/omlx --HEAD --with-custom-kernel

注意：自定义内核构建需要安装完整的 Xcode（仅 Command Line Tools 不够）。

🔧 方式三：从源码部署

适合需要定制或二次开发的开发者 。

步骤 1：克隆仓库

1
2
git clone https://github.com/jundot/omlx.git
cd omlx

步骤 2：安装核心组件

1
2
# 仅安装核心
pip install -e .

步骤 3：安装可选组件

1
2
3
4
5
# 安装 MCP 支持
pip install -e ".[mcp]"

# 安装开发依赖（用于测试和贡献）
pip install -e ".[dev]"

步骤 4：安装原生自定义内核（可选）

对于 GLM-5.2 / MiniMax M3 / Qwen3.5 等模型家族，建议构建原生自定义内核以获得显著性能提升 ：

1
OMLX_WITH_CUSTOM_KERNEL=1 pip install -e .

验证内核是否安装成功：

1
python -c "from omlx.custom_kernels import native_kernel_status; print(native_kernel_status())"

⚠️ 重要：自定义内核构建需要完整的 Xcode（不仅仅是 Command Line Tools）。安装完整 Xcode：

1
xcode-select --install  # 如果尚未安装

如果遇到 xcrun: error: unable to find utility "metal" 错误，说明缺少 Metal 工具链 。

步骤 5：运行服务器

1
omlx serve --model-dir ~/models

🔄 方式四：作为后台服务运行

如果通过 Homebrew 安装，可以将 oMLX 作为 macOS 后台服务运行，支持崩溃自动重启 。

启动/停止服务

1
2
3
4
5
6
7
8
9
10
11
# 启动服务（崩溃时自动重启）
brew services start omlx

# 停止服务
brew services stop omlx

# 重启服务
brew services restart omlx

# 查看服务状态
brew services info omlx

服务配置

服务使用零配置默认值运行：

  • 模型目录：~/.omlx/models
  • 端口：8000
  • 日志位置：
    • 服务日志：$(brew --prefix)/var/log/omlx.log（stdout/stderr）
    • 服务器日志：~/.omlx/logs/server.log（结构化应用日志）

自定义配置

要自定义配置，可以：

  1. 设置环境变量：

    1
    2
    export OMLX_MODEL_DIR=/path/to/models
    export OMLX_PORT=8001

  2. 运行一次命令以持久化配置：

    1
    omlx serve --model-dir /your/path --port 8001

    配置会保存到 ~/.omlx/settings.json，后续服务会自动使用 。

🗂️ 模型管理与配置

模型目录结构

将 --model-dir 指向包含 MLX 格式模型子目录的目录。支持两级目录结构 ：

1
2
3
4
5
6
~/models/
├── Step-3.5-Flash-8bit/
├── Qwen3-Coder-Next-8bit/
├── gpt-oss-120b-MXFP4-Q8/
├── Qwen3.5-122B-A10B-4bit/
└── bge-m3/              # 嵌入模型

支持的模型类型

oMLX 会自动检测并分类模型 ：

类型 支持的模型
LLM mlx-lm 支持的所有模型
VLM Qwen3.5 系列、GLM-4V、Pixtral 等
OCR DeepSeek-OCR、DOTS-OCR、GLM-OCR
嵌入 BERT、BGE-M3、ModernBERT
重排序 ModernBERT、XLM-RoBERTa

常用 CLI 配置参数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 设置模型目录
omlx serve --model-dir ~/models

# 设置内存限制（已加载模型）
omlx serve --model-dir ~/models --max-model-memory 32GB

# 设置进程级内存限制（默认: RAM - 8GB）
omlx serve --model-dir ~/models --max-process-memory 80%

# 启用 SSD KV 缓存
omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache

# 设置热缓存大小（内存中的 KV 缓存比例）
omlx serve --model-dir ~/models --hot-cache-max-size 20%

# 调整最大并发请求数（默认: 8）
omlx serve --model-dir ~/models --max-concurrent-requests 16

# 设置 API Key 认证
omlx serve --model-dir ~/models --api-key your-secret-key

# 使用 HuggingFace 镜像（受限地区）
omlx serve --model-dir ~/models --hf-endpoint https://hf-mirror.com

所有配置也可以通过 Web 管理面板 /admin 进行设置，并持久化到 ~/.omlx/settings.json 。

🌐 核心功能与 API

Web 管理后台

服务器启动后，访问 http://localhost:8000/admin 可以 ：

  • 实时监控模型占用和状态
  • 手动加载/卸载模型
  • 固定（Pin）模型，防止被 LRU 算法自动卸载
  • 一键下载 HuggingFace 模型
  • 内置聊天测试（支持多模态）
  • 一键运行性能基准测试
  • 设置 OpenClaw、OpenCode、Codex 等工具集成

API 兼容性

oMLX 提供 OpenAI 和 Anthropic 兼容 API ：

端点 说明
POST /v1/chat/completions 聊天补全（支持流式）
POST /v1/completions 文本补全（支持流式）
POST /v1/messages Anthropic Messages API
POST /v1/embeddings 文本嵌入
POST /v1/rerank 文档重排序
GET /v1/models 列出可用模型

工具调用与结构化输出

oMLX 支持多种模型家族的 Tool Calling 格式 ：

模型家族 格式
Llama、Qwen、DeepSeek 等 JSON <tool_call>
Qwen3.5 系列 XML <function=...>
Gemma <start_function_call>
GLM (4.7, 5) XML 格式
MiniMax 命名空间 XML
Mistral [TOOL_CALLS]

🔧 故障排除

1. 自定义内核构建失败

问题：xcrun: error: unable to find utility "metal"

解决方案：安装完整的 Xcode（不仅仅是 Command Line Tools）：

1
2
xcode-select --install
# 或从 App Store 下载完整 Xcode

2. 服务器无法启动 / 端口被占用

问题：端口 8000 已被占用

解决方案：指定其他端口运行 ：

1
omlx serve --model-dir ~/models --port 8001

3. 模型加载后内存不足

问题：系统卡顿或模型无法加载

解决方案：

  • 检查进程内存限制（默认：RAM - 8GB）
  • 调低 --max-model-memory 参数
  • 使用更小量化级别的模型（如 4bit 而非 8bit）

4. 查看日志

1
2
3
4
5
# 查看服务日志（Homebrew 服务）
cat $(brew --prefix)/var/log/omlx.log

# 查看服务器日志
cat ~/.omlx/logs/server.log

5. 开启调试模式

1
omlx serve --model-dir ~/models --debug

📚 总结

你的需求 推荐方案
日常使用，不想碰终端 macOS 应用（DMG）
开发者，习惯命令行 Homebrew + brew services
需要定制或贡献代码 源码部署
集成到 Harbor 平台 使用 Harbor 的 oMLX 服务

oMLX 充分利用 Apple Silicon 的 MLX 框架，为 Mac 用户提供了高性能、易管理的本地 LLM 推理方案。其分层 KV 缓存和连续批处理特性，使其在代码辅助等场景中表现优异 。

更多详细信息请参考：