oMLX：Mac 菜单栏管理本地 LLM 推理服务

LLM 推理，为 Mac 优化持续批处理与分级 KV 缓存，直接从菜单栏管理。

junkim.dot@gmail.com · https://omlx.ai/me

Install · Quickstart · Features · Models · CLI Configuration · Benchmarks · oMLX.ai

English · 中文 · 한국어 · 日本語

我试过的每一个 LLM 服务器都让我在便利性和可控性之间二选一。我想要把日常使用的模型常驻内存，更重的模型按需自动换出，设置上下文限制——并且全部从菜单栏管理。

oMLX 将 KV 缓存在热（内存）层和冷（SSD）层之间持久化——即使对话中途上下文发生变化，所有历史上下文仍会保留在缓存中并在请求间复用，使得本地 LLM 在配合 Claude Code 等工具进行实际编码工作时变得可行。这就是我构建它的原因。

从 Releases 下载 .dmg，拖到 Applications 目录，完成。应用内置自动更新，以后升级只需一次点击。macOS 应用还会安装一个轻量的 ~/.omlx/bin/omlx CLI 封装，使终端命令和 Apple Shortcuts 可以控制应用管理的服务器。

brew tap jundot/omlx https://github.com/jundot/omlx
brew install jundot/omlx/omlx

# 升级到最新版本
brew update && brew upgrade omlx

# 作为后台服务运行（崩溃后自动重启）
omlx start

# 可选：MCP（Model Context Protocol）支持
/opt/homebrew/opt/omlx/libexec/bin/pip install mcp

可选的 GLM-5.2 / MiniMax M3 原生自定义内核目前需要 HEAD 构建：

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

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .          # 仅核心部分
pip install -e ".[mcp]"   # 带 MCP（Model Context Protocol）支持

# GLM-5.2 / MiniMax M3 / Qwen3.5 原生自定义内核（强烈建议在服务这些模型系列时启用——
# 见下方说明）
OMLX_WITH_CUSTOM_KERNEL=1 pip install -e .

需要 macOS 15.0+（Sequoia）、Python 3.11–3.13，以及 Apple Silicon（M1/M2/M3/M4）。

关于原生自定义内核的说明：普通的 pip install -e . 不会编译它们，受影响的模型系列会静默回退到慢得多的通用路径——对于 GLM-5.2，使用内核时融合的 DSA prefill 快约 30 倍（在 M3 Ultra 上实测 845 vs 约 29 tok/s），且回退方案也会消耗更多内存（#2137）。编译它们需要 Metal 工具链，单独的命令行工具不提供此支持（xcrun: error: unable to find utility "metal"）：需要安装完整 Xcode，或使用官方 DMG（其中内核已预编译）。Homebrew 可以通过 brew install jundot/omlx/omlx --HEAD --with-custom-kernel 编译，但该构建同样需要完整 Xcode。验证安装：

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

从 Applications 文件夹启动 oMLX。Welcome 界面会引导你完成三个步骤——模型目录、服务器启动、首个模型下载。就这样。连接 OpenClaw、OpenCode、Codex、Hermes Agent 或 Copilot，详见 Integrations。

# 托管的后台服务器（macOS 应用或 Homebrew 安装）
omlx start
omlx stop
omlx restart

# 前台服务器，绑定当前终端
omlx serve --model-dir ~/models

服务器自动从子目录发现 LLM、VLM、embedding 模型和 reranker。任何兼容 OpenAI 的客户端都可以连接到 http://localhost:8000/v1。内置聊天界面也可在 http://localhost:8000/admin/chat 访问。

如果通过 Homebrew 安装，可以将 oMLX 作为托管后台服务运行：

omlx start                    # 通过 brew services 启动
omlx stop                     # 停止
omlx restart                  # 重启

brew services start omlx    # 启动（崩溃后自动重启）
brew services stop omlx     # 停止
brew services restart omlx  # 重启
brew services info omlx     # 查看状态

服务以零配置默认值运行 omlx serve（~/.omlx/models，端口 8000）。omlx start、omlx stop 和 omlx restart 是可移植的生命周期命令；Homebrew 安装会将其委托给 brew services。如需自定义，可以设置环境变量（OMLX_MODEL_DIR、OMLX_PORT 等），或运行一次 omlx serve --model-dir /your/path 将设置持久化到 ~/.omlx/settings.json。

日志写入两个位置：

服务日志：$(brew --prefix)/var/log/omlx.log（stdout/stderr）

服务器日志：~/.omlx/logs/server.log（结构化应用日志）

在 Apple Silicon 上支持文本 LLM、视觉语言模型（VLM）、OCR 模型、embedding 和 reranker。

/admin 提供 Web UI，用于实时监控、模型管理、聊天、性能基准测试和逐模型设置。支持英语、韩语、日语、汉语、法语、俄语、西班牙语和巴西葡萄牙语。所有 CDN 依赖均已内置，确保完全离线运行。

实验性多 Mac 推理

源码构建可以将一个下载好的语言模型通过 MLX pipeline ranks 分割到内存不同的 Mac 上，使用 Ring 或 Thunderbolt RDMA/JACCL。Cluster 仪表板处理只读节点发现、严格的 SSH/运行时验证、字节级不等分片规划、实测计算/链接重平衡、容量感知执行调优、激活，以及两台 Mac 上的实时分片/性能图。并发、均衡和吞吐量模式暴露了合并批处理、提示缓存亲和性、轮转 KV 限制、Ring 连接调优，以及能力门控的实验性纯 token 输出路径。详见 Distributed inference across Macs 中的设置、安全边界、当前限制和物理硬件验证清单。

视觉语言模型

使用与文本 LLM 相同的持续批处理和分级 KV 缓存栈运行 VLM。支持多图聊天、base64/URL/file 图片输入，以及带视觉上下文的工具调用。OCR 模型（DeepSeek-OCR、DOTS-OCR、GLM-OCR）会自动检测并使用优化提示。

分级 KV 缓存（热 + 冷）

受 vLLM 启发的基于块的 KV 缓存管理，带前缀共享和写时复制。缓存在两个层级间运作：

热层（RAM）：频繁访问的块保留在内存中以供快速访问。

冷层（SSD）：当热缓存满了，块会以 safetensors 格式卸载到 SSD。下一次请求如果带匹配的前缀，它们会从磁盘恢复而非从头重新计算——即使服务器重启后亦如此。

通过 mlx-lm 的 BatchGenerator 处理并发请求。最大并发数可通过 CLI 或管理面板配置。

Claude Code 优化

支持运行较小上下文模型的上下文扩展，以便与 Claude Code 配合使用。缩放报告的 token 计数，使自动压缩在正确时机触发，SSE keep-alive 防止长 prefill 期间的读取超时。

在同一服务器内加载 LLM、VLM、embedding 模型和 reranker。模型通过自动和手动控制相结合的方式管理：

LRU 驱逐：当内存不足时，自动驱逐最近最少使用的模型。

手动加载/卸载：管理面板中的交互式状态徽章让你可以按需加载或卸载模型。

模型固定：将常用模型固定以保持始终加载状态。

逐模型 TTL：可为每个模型设置空闲超时，空闲一定时间后自动卸载。

进程内存强制：总内存限制（默认：系统 RAM - 8GB）防止全局 OOM。

可直接从管理面板配置采样参数、聊天模板参数、TTL、模型别名、模型类型覆盖等。变更立即生效，无需重启服务器。

模型别名：设置自定义的 API 可见名称。/v1/models 返回别名，请求同时接受别名和目录名。

模型类型覆盖：无论自动检测结果如何，手动将模型设置为 LLM 或 VLM。

Profiles：保存每个模型的命名设置包，可从管理面板切换。一个 profile 可以选择作为独立模型暴露：/v1/models 也会列出 <model>:<profile>（例如 qwen3-8b:thinking），它在同一个引擎上服务，profile 的设置随每个请求叠加——无需额外内存，无需重载。当基础模型有别名时，暴露的 ID 宣传为 <alias>:<profile>；目录名形式仍然可用，就像基础模型一样。

直接在管理面板与任何已加载的模型对话。支持对话历史、模型切换、深色模式、推理模型输出，以及 VLM/OCR 模型的图片上传。

直接在管理面板中搜索和下载 HuggingFace 上的 MLX 模型。浏览模型卡片、查看文件大小，一键下载。

一键从管理面板配置 OpenClaw、OpenCode、Codex、Hermes Agent、Copilot 和 Pi。无需手动编辑配置。

性能基准测试

从管理面板一键跑基准测试。测量 prefill (PP) 和 text generation (TG) 每秒令牌数，并测试部分前缀缓存命中以获得真实性能数据。

原生 Swift / SwiftUI 菜单栏应用（非 Electron）。无需打开终端即可启动、停止和监控服务器。包括持久化服务统计（重启后保留）、崩溃自动重启和内置自动更新。

OpenAI 和 Anthropic API 的直接替代。支持流式使用统计（stream_options.include_usage）、Anthropic 自适应思考和视觉输入（base64、URL）。

工具调用与结构化输出

支持 mlx-lm 中所有可用的函数调用格式、JSON schema 验证和 MCP 工具集成。工具调用需要模型的 chat template 支持 tools 参数。以下模型系列通过 mlx-lm 内置工具解析器自动检测：

未在上述列表中的模型，如果其 chat template 接受 tools 参数且输出使用公认的 <tool_call> XML 格式，仍可能工作。对于启用工具的流式输出，助手文本逐步发送，已知的工具调用控制标记从可见内容中抑制；结构化工具调用在解析完整个回合后发送。

将 --model-dir 指向包含 MLX 格式模型子目录的目录。两级组织文件夹（例如 mlx-community/model-name/）也支持。

~/models/
├── Step-3.5-Flash-8bit/
├── Qwen3-Coder-Next-8bit/
├── gpt-oss-120b-MXFP4-Q8/
├── Qwen3.5-122B-A10B-4bit/
└── bge-m3/

模型按类型自动检测。你也可以直接从管理面板下载模型。

# 托管后台服务器（macOS 应用或 Homebrew 安装）
omlx start
omlx stop
omlx restart

# 使用默认设置启动（memory guard tier = balanced，通过 admin UI 管理）
omlx serve --model-dir ~/models

# 启动时选择 memory guard tier
omlx serve --model-dir ~/models --memory-guard safe

# 设置自定义 memory guard 上限（GB）
omlx serve --model-dir ~/models --memory-guard-gb 48

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

# 设置内存热缓存大小
omlx serve --model-dir ~/models --hot-cache-max-size 20%

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

# 配合 MCP 工具使用
omlx serve --model-dir ~/models --mcp-config mcp.json

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

# API key 认证
omlx serve --model-dir ~/models --api-key your-secret-key
# 本地 localhost：通过管理面板全局设置跳过验证

所有设置也可以通过 /admin 的 Web 管理面板配置。设置持久化到 ~/.omlx/settings.json，且 CLI 参数优先。

FastAPI Server (OpenAI / Anthropic API)
    │
    ├── EnginePool（多模型、LRU 淘汰、TTL、手动加载/卸载）
    │   ├── BatchedEngine（LLM、continuous batching）
    │   ├── VLMEngine（视觉语言模型）
    │   ├── EmbeddingEngine
    │   └── RerankerEngine
    │
    ├── ProcessMemoryEnforcer（总内存限制、TTL 检查）
    │
    ├── Scheduler（FCFS、可配置并发）
    │   └── mlx-lm BatchGenerator
    │
    └── Cache Stack
        ├── PagedCacheManager（GPU、块级、CoW、前缀共享）
        ├── Hot Cache（内存层、写回）
        └── PagedSSDCacheManager（SSD 冷层、safetensors 格式）

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e ".[dev]"
pytest -m "not slow"

原生 SwiftUI 应用位于 apps/omlx-mac/。需要 Xcode 26.5+ 和 Python 3.11+。venvstacks 被声明为开发依赖，所以 pip install -e ".[dev]"（或 uv sync --dev）会引入固定版本。构建脚本也会回退到 uvx venvstacks 或 pipx run venvstacks（如果你更喜欢主机全局工具运行器）。

# 准备可运行的 oMLX.app（xcodebuild + venvstacks Python 层 + ad-hoc 签名）
apps/omlx-mac/Scripts/build.sh release

# 产物位于 apps/omlx-mac/build/Stage/oMLX.app
open apps/omlx-mac/build/Stage/oMLX.app

# 强制全新 venvstacks 重建（否则按指纹缓存）
apps/omlx-mac/Scripts/build.sh release --rebuild-donor

# 使用可选的 GLM-5.2 / MiniMax M3 原生自定义内核打包
apps/omlx-mac/Scripts/build.sh release --with-custom-kernel

首次冷构建需要 10–20 分钟（venvstacks Python 层组装）。后续构建重用缓存的 packaging/_export/，大约 4 分钟完成。详见 packaging/README.md 的层配置和 apps/omlx-mac/ 的 Swift 源码。

欢迎贡献！详见贡献指南。

Bug 修复与改进

性能优化

文档改进

MLX 和 mlx-lm——Apple 提供

mlx-vlm——Apple Silicon 上的视觉语言模型推理

vllm-mlx——oMLX 起源于 vllm-mlx v0.1.0，在多模型服务、分层 KV 缓存、支持完整分页缓存的 VLM、管理面板和 macOS 菜单栏应用方面显著演进

venvstacks——macOS 应用包的可移植 Python 环境分层

mlx-embeddings——Apple Silicon 的嵌入模型支持

dflash-mlx——Apple Silicon 上的块扩散推测解码

MTPLX——Lightning MTP 的 verify-shape Metal 内核由 Youssof Altoukhi 提供的 MTPLX 驱动，这也激发了 depth-k 流水线

mlx-serve——融合的 GDN 验证预工作内核改编自 mlx-serve 移植的 mlxfast-challenge qwen35_packed_gdn_prework 内核

SiliconScope——菜单栏统计采用 Kennt Kim 的 SiliconScope 设计和渲染方法，这也启发了节能重新渲染门控