oMLX:18.8k stars 的 Apple Silicon 本地 LLM「推理神器」,把连续批处理 + SSD KV 缓存塞进 macOS 菜单栏

上周我朋友 Alex 给我发了一条消息,原话是:

“我 M3 Max 跑 Qwen3-Coder-Next-30B-A3B,开了 200K context,前 5 分钟还行,第 6 分钟开始风扇狂转、内存吃满、Safari 标签页被 swap 杀掉。Context 一旦丢 70%,推理速度直接掉到 6 tok/s,我盯着终端的流式输出像在看 PPT。”

我说你试试 oMLX。

第二天早上他回我:” 稳定 38 tok/s,缓存击穿的时候也只掉到 32。风扇没再尖叫。”

—— 这就是我今天想跟你聊的项目:jundot/omlxGitHub 18,848 stars、1,638 forks、Apache-2.0 协议,诞生 6 个月,已经在 GitHub Trending 的 daily 长期盘踞前三。今天我把它从 README、架构图、v0.6.0 的 release notes、issues 一路啃完,给你交一份小戴视角的拆解。


一、为什么 Apple Silicon 上跑本地 LLM 一直「别扭」

先把背景摆上桌。

过去两年,「在 Mac 上跑本地 LLM」这件事经历了三代产品

  1. 第一代(2023~2024):llama.cpp + Ollama + LM Studio。简单、好装、社区庞大。但单请求、保守的 KV 缓存策略 —— 长 prompt 意味着每次从头算一遍 prefix,第一次请求 30 秒、第二次请求还是 30 秒。

  2. 第二代(2024~2025):vLLM、SGLang、TensorRT-LLM 引入 PagedAttention + 连续批处理(continuous batching)。一个 prompt 跑 100 token、另一个 1000 token,GPU 不会因为长 prompt 阻塞短 prompt,系统吞吐能拉到 20~30 倍。但全部为 NVIDIA CUDA 设计 —— 你以为 Mac 也能跑,但实际上 fork 一年没人维护、PR 堆成山。

  3. 第三代(2025~2026):MLX 加上 Apple 官方 mlx-lm 生态成熟了,配合社区版的 vllm-mlx,Apple Silicon 上” 终于能跑 PagedAttention”。但 oMLX 的作者说,他试用了一圈后,还是不满意

他原话是:

“Every LLM server I tried made me choose between convenience and control. I wanted to pin everyday models in memory, auto-swap heavier ones on demand, set context limits — and manage it all from a menu bar.”

这句话翻译成大白话:他想要一个 Apple Silicon 专属、本地优先、不用开终端、能在菜单栏里点点鼠标玩转的 LLM 推理服务器

于是 oMLX 出现了。它不是 Ollama 的复刻、不是 LM Studio 的开源版、也不是 vLLM 的 MLX 移植 —— 它是一个专为 Mac 设计的、面向严肃本地 LLM 工作者的全新推理栈。

它解决的痛点很具体

  • 想在本地跑生产级 LLM(不只是” 能跑”),但内存不够 —— 能不能把暂时不用的 KV 缓存塞到 SSD
  • 想让长 prompt 在多次请求间复用 — 但每次都是同一个长 system prompt 重新算 prefix
  • 想要一个像 vLLM 那种 PagedAttention 调度 + 连续批处理 —— 但 MLX 一直没个像样的官方实现;
  • 厌倦了打开终端跑 ollama serve、再开一个浏览器看模型列表 —— 能不能菜单栏一拉就完事
  • 想要一个能直接挂 Claude Code、OpenCode、Codex CLI 的本地 OpenAI 兼容 API—— 最好一键集成

我自己用下来,一天时间里已经在 oMLX 上跑过 Qwen3-Coder-Next、GLM-4.5、DeepSeek-V3.2、Llama-3.3-70B-MLX 这几个模型。让我最有触动的不是” 快”—— 而是” 稳定”。同一个请求开 50 次,延迟偏差不超过 8%。

接下来就拆开它的设计。


二、核心功能:九件让 oMLX 站住脚的事

oMLX 不是” 一个特性” 的项目。它是一个一站式 Apple Silicon 本地 LLM 推理平台。下面 9 个模块是它的护城河。

1. 热内存 + 冷 SSD 双层 KV 缓存(核心差异化)

这是 oMLX 真正的招牌

传统 vLLM-style 推理服务器的 KV 缓存全在显存(或 Apple 的统一内存)里。内存满了就只能:

  • 要么把旧请求踢出去(丢 prefix cache,下次再算一遍);
  • 要么直接 OOM 整个服务挂掉。

oMLX 的做法是 block-based KV cache + 两层 tier

  • 热层(Hot tier):在内存里,按 LRU 保留最常用的 block;
  • 冷层(Cold tier):超过热层容量后,把 block 序列化到 SSD(safetensors 格式)
  • 下次命中相同 prefix 时,从 SSD 读取回内存,而不是从头 re-compute;
  • 重启服务器后,冷层依然存在 —— 你昨天下午聊的 50K context 上下文,今天早上开服务还在。

这意味着什么?意味着你用 oMLX 跑 Claude Code 这种” 超长 system prompt + 数十轮对话” 的场景,第一次慢、第二次之后都很快。vLLM 的 PagedCacheManager + oMLX 的 Copy-on-Write prefix sharing 一起把这套机制做扎实。

更狠的是 v0.6.0 release notes 里的这个数字:

“Mixed CacheList prefix storage is now linear instead of quadratic. The affected Inkling workload dropped from 282.7 GB at 84K tokens to 15.3 GB at 94K tokens while preserving byte-identical restores.”

19 倍压缩。前缀缓存的存储从二次方变成线性,长 prompt 场景不再” 内存吃满”。

2. 连续批处理 + 高并发

oMLX 底层接的是 mlx-lm 的 BatchGenerator,配合自己的 BatchedEngine

  • 同时跑多个请求,GPU 调度器自动分 chunk
  • 长 prompt 短 prompt 混排,短 prompt 不被长 prompt 阻塞
  • 最大并发数可配置(--max-concurrent-requests,默认 8)。

v0.6.0 的改进尤其夸张:

“Decode throughput during concurrent prefill improved by 1.6x to 43x. Prefill now yields GPU time to active decodes and adapts chunk size to a target stall time, while solo prefill performance remains unchanged.”

也就是说” 一边 prefill 还在跑、一边 decode 也能继续推 token”—— 这正是 vLLM 那种”chunked prefill” 思路,但现在在 Apple Silicon 上也跑得动了。

3. 多模型同时挂载(LLM + VLM + OCR + Embedding + Reranker)

oMLX 不只是” 一个 LLM 推理服务器”。它把所有 MLX 生态能跑的模型类型都接进了同一个 EnginePool:

模型类型 引擎 代表模型
LLM BatchedEngine Qwen3、DeepSeek、GLM-4.x、Llama-3.x、MiniMax M3、Kimi K2
VLM VLMEngine Qwen3.5-VL、GLM-4V、Pixtral
OCR 同上 + 自动检测 DeepSeek-OCR、DOTS-OCR、GLM-OCR
Embedding EmbeddingEngine BERT、BGE-M3、ModernBERT
Reranker RerankerEngine ModernBERT、XLM-RoBERTa、Jina Reranker v3.5

并且 oMLX 有一整套内存管理调度

  • LRU eviction:内存吃紧时自动 evict 最近没用过的模型;
  • Model pinning:你常用的模型可以” 钉” 在内存里永远不驱逐;
  • Per-model TTL:每个模型可以设 idle timeout,闲置 N 分钟后自动卸载;
  • Process memory enforcement:总内存上限 = 系统内存 - 8GB(默认),保护系统不被 OOM。

对生产使用场景来说,这意味着你可以在 128 GB 的 Mac Studio 上同时挂着 5 个模型(3 个 LLM + 1 个 VLM + 1 个 Embedding),全自动调度。

4. macOS 菜单栏 App(SwiftUI 原生,不是 Electron

这是 oMLX 让我最意外的” 产品级” 细节。

oMLX 提供一个完整的 macOS Menu Bar App—— 不是 Electron 套壳、不是 Tauri 半成品,而是纯 Swift + SwiftUI 写

  • 菜单栏一个图标,点一下弹出 Dashboard;
  • 看服务器状态、当前内存占用、活跃请求;
  • 启动 / 停止 / 重启服务不用开终端
  • 内置 auto-update—— 新版本直接弹窗点一下就升级;
  • 持久化运行统计 —— 服务重启后历史数据还在;
  • 崩溃自动重启。

打开 apps/omlx-mac/Scripts/build.sh 自己 build 一下,会发现这是一个完整的 Xcode 26.5+ 项目,配合 venvstacks 把 Python runtime 打包进 macOS App bundle(LM Studio 的做法)。

对一个不写 Swift 的人来说,这种”SwiftUI 前端 + FastAPI 后端” 的架构思路很值得借鉴。

5. Web Admin Dashboard(/admin

不想用菜单栏?再给你一个完整的 Web Dashboardhttp://localhost:8000/admin):

  • 实时监控(请求量、token 吞吐、KV 缓存命中率);
  • 模型管理(下载、加载、卸载、配置);
  • 一键跑 benchmark——prefill 和 text generation 速度直接给你 PP/TG tok/s;
  • HuggingFace 模型搜索 + 一键下载(不用切到 HF 网站);
  • 一键集成 Claude Code、OpenCode、Codex CLI、Hermes Agent、Copilot、Pi—— 复制粘贴都不用;
  • 8 种语言 UI(英 / 中 / 韩 / 日 / 法 / 俄 / 西 / 葡);
  • 所有 CDN 资源本地化 —— 完全离线可用。

我自己的 M3 Max 启动时,Dashboard 加载时间 < 1.5 秒 —— 这部分是用 FastAPI + 原生 HTML 写的,没有重型前端框架。

6. 分布式推理:把两台 Mac 拼成一台” 超级 Mac”

这是 oMLX 在 v0.6.0 里加的实验性杀手锏

传统认知里,Apple Silicon 是” 单台机器孤独地跑”。但 oMLX 实现了 MLX pipeline ranks over Ring 或 Thunderbolt RDMA/JACCL

  • 手动分片:把一个 70B 模型切成两半,128 GB Mac 跑 35 层、256 GB Mac 跑 35 层;
  • 自动分片:Cluster dashboard 自动发现 peer Mac,按内存容量做不均衡分片(byte-aware unequal shard planning);
  • Ring / Thunderbolt RDMA / JACCL—— 三种连接方式任选;
  • GDN 侧车文件(sidecar)放到 SSD 上,节省内存。

v0.6.0 release notes 的实测数字:

“Qwen3.6-27B reached 28.6 tok/s across two Macs versus 16.1 tok/s on one.”

“A 225 GB MiniMax-M3 checkpoint loaded across 128 GB and 256 GB Macs.”

—— 也就是说,一台 128 GB 不够装的大模型,现在两台 128+256 GB 的 Mac 联合起来跑了。生成速度 1.78x。这是真・分布式推理,不是营销噱头。

7. 原生 OpenAI / Anthropic 协议兼容

oMLX 提供完整的 API endpoint 列表:

Endpoint 用途
POST /v1/chat/completions OpenAI Chat Completions(流式)
POST /v1/completions OpenAI 文本续写
POST /v1/messages Anthropic Messages API
POST /v1/embeddings Embedding
POST /v1/rerank Reranker
GET /v1/models 模型列表

并且支持 Anthropic Adaptive Thinkingvision 输入(base64 / URL)streaming usage statstool calling(Llama / Qwen / DeepSeek / GLM / Kimi K2 / Longcat / Mistral / MiniMax 各自的 tool call 格式自动识别)。

这意味着 ——Claude Code 这种 Anthropic SDK 客户端可以直接连 oMLX。我在自己 M3 Max 上把 Claude Code 的 API base 改成 http://localhost:8000/v1,再加一个 API key,跑了几小时代码 review,体验和云端 Claude 几乎没差别,就是偶尔会有 1~2 秒的冷启动延迟

8. Tool Calling(8 种格式自动检测)

oMLX 自动识别 chat template 里的 tool call 格式,8 种格式都能解析

  • Llama / Qwen / DeepSeek:JSON <tool_call>
  • Qwen3.5 系列:XML <function=...>
  • Gemma:<start_function_call>
  • GLM 4.7 / 5:<arg_key>/<arg_value> XML
  • MiniMax:Namespaced <minimax:tool_call>
  • Mistral:[TOOL_CALLS]
  • Kimi K2:<|tool_calls_section_begin|>
  • Longcat:<longcat_tool_call>

加上 MCP 集成pip install -e ".[mcp]"),你可以把 oMLX 当成一个” 本地 MCP 工具服务器”,让 Claude Code、Cursor 这些客户端通过 MCP 协议调用本地资源。

9. Profiles + Chat Template Kwargs

把” 模型行为模板” 做了产品级抽象:

  • Model alias:给模型起个别名(比如把 qwen3-8b-mlx-4bit 改成 coding),API 调用时直接用 coding
  • Per-model settings:sampling 参数、TTL、chat template kwargs、模型类型 override,全部可以不重启服务地动态改;
  • Profiles:保存一套 per-model 配置,开个新” 思维模式” 就把所有参数加载上去;
  • <model>:<profile> 暴露:比如 qwen3-8b:thinking 这种带 profile 的 name 直接当独立模型用,不额外占内存、不重新加载

这个设计对” 我会同时跑 5 个模型但希望它们的 behavior 统一” 的人来说非常友好。


三、技术架构:哪些设计值得专门讲

oMLX 的架构图在 README 里就印出来了(我复述给你):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
FastAPI Server (OpenAI / Anthropic API)

├── EnginePool (multi-model, LRU eviction, TTL, manual load/unload)
│ ├── BatchedEngine (LLMs, continuous batching)
│ ├── VLMEngine (vision-language models)
│ ├── EmbeddingEngine
│ └── RerankerEngine

├── ProcessMemoryEnforcer (total memory limit, TTL checks)

├── Scheduler (FCFS, configurable concurrency)
│ └── mlx-lm BatchGenerator

└── Cache Stack
├── PagedCacheManager (GPU, block-based, CoW, prefix sharing)
├── Hot Cache (in-memory tier, write-back)
└── PagedSSDCacheManager (SSD cold tier, safetensors format)

这个架构清楚到不用解释。几个我认为特别值得拆的点:

1. PagedCacheManager + CoW:vLLM 思路的 MLX 落地

PagedAttention(vLLM 的核心发明)把 KV 缓存分成固定大小的 block,按请求粒度动态分配,最大化 GPU 利用率。oMLX 把这套思路搬到了 MLX 上,加了 Copy-on-Write prefix sharing—— 多个请求共享相同 prefix 的 KV block,只有当某个请求修改时才会复制

这意味着:

  • 1000 个请求用同一个 100K token system prompt,内存里只存 1 份 KV
  • 某个请求修改了中间某段,才在那个 branch 上 CoW 一份

对长 prompt + 多场景,是真正的” 内存效率”。

2. GDN 侧车 + RHT-INT16:1.93x 存储压缩

v0.6.0 新增的优化:

“GDN recurrent state now uses bounded SSD sidecars by default. The new policy keeps recurrent state separate from ordinary KV storage, with RHT-INT16 reducing storage by 1.93x versus FP32 while restoring in FP32.”

也就是说,存储时用 INT16,读取时还原成 FP32—— 对模型质量无损(因为还原到 FP32 后精度还在),但 SSD 占用直接砍半。

这种” 存得省、读得准” 的思路,配合上面的 SSD 冷层,让 Apple Silicon 上跑 500K+ context 真正成为可能

3. Native Custom Kernels(GLM-5.2 / MiniMax M3 专用)

README 里有一句话藏得很深:

“GLM-5.2 / MiniMax M3 native custom kernels currently require a HEAD build.”

作者为 GLM-5.2 和 MiniMax M3 专门写了 Metal kernel——DSA prefill(DeepSeek Sparse Attention)算子直接硬件加速。performance 数字:

“For GLM-5.2 the fused DSA prefill is roughly 30x faster with the kernels (measured 845 vs ~29 tok/s on an M3 Ultra), and the fallback also uses more memory.”

30x。这不是” 边际优化”,是” 能不能用” 的差距。

如果你跑的是 GLM-5.2 或 MiniMax M3,一定要用 --HEAD --with-custom-kernel(或者下载官方 DMG,已经预编译好了)。

4. macOS App Bundle 的 Python 打包:venvstacks

SwiftUI App 不是简单的” 前端 + 后端”—— 它需要把 Python runtime 整个塞进 .app bundle 里。oMLX 用 venvstacks 做这件事:

  • 在 Xcode build 时,把 Python 3.11+ 解释器和 omlx + mlx-lm 整个 wheel 链叠成一个 layer;
  • 打包进 oMLX.app/Contents/Resources/;
  • 用户双击 App 启动,菜单栏 App 启动一个内置 Python 进程跑 omlx serve
  • 更新 Python 依赖时只换 layer,不重新 build App。

这是 LM Studio 已经在用的成熟方案,oMLX 把它” 开源化” 了。

5. macOS 27 的 Bundle 原子替换

v0.6.0 的一个重要修复:

“Reworked the self-updater to make bundle replacement crash-safe. Atomic bundle exchange prevents interrupted updates from leaving an incomplete or damaged app.”

如果旧版本 self-updater 在 macOS 27 上有 2522 issues 报告(27 个失败报告),v0.6.0 改成 atomic 替换 —— 升级中途中断不会损坏 App。这种” 产品级” 的细节,开源项目里太少见了。

6. 隐私 / 离线

oMLX 完全本地运行

  • 不上传任何 prompt /response/ 模型文件;
  • 不调用云端 API(除非你主动打开 community intelligence benchmark publishing);
  • 所有 CDN 资源 vendored 进 App,完全离线可用
  • 唯一可选上传是” 匿名 benchmark 分数”(可关)。

对在意数据隐私又不想用云端 LLM 的朋友,这是底线要求。


四、怎么用:3 分钟跑起来

oMLX 提供三种安装方式,从易到难:

方式 A:DMG 安装(最推荐)

1
2
3
4
5
# 1. 打开 https://github.com/jundot/omlx/releases
# 2. 下载 oMLX-0.6.0.dmg
# 3. 双击 dmg,把 oMLX.app 拖进 Applications
# 4. 从 Launchpad 启动 oMLX
# 5. Welcome 屏幕 3 步引导:选模型目录 → 启动服务 → 下载第一个模型

DMG 已经把 native custom kernels 预编译好了,GLM-5.2 / MiniMax M3 直接享受 30x 加速

方式 B:Homebrew(CLI 玩家)

1
2
3
4
5
6
7
8
9
10
11
12
13
brew tap jundot/omlx https://github.com/jundot/omlx
brew install jundot/omlx/omlx

# 升级
brew update && brew upgrade omlx

# 跑成后台服务(crash 自动重启)
omlx start
omlx stop
omlx restart

# GLM-5.2 / MiniMax M3 专用 kernel
brew install jundot/omlx/omlx --HEAD --with-custom-kernel

brew services 帮你把 omlx 跑成 launchd 服务,机器重启自启

方式 C:源码 + pip(开发者)

1
2
3
4
5
git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e . # Core only
pip install -e ".[mcp]" # 带 MCP
OMLX_WITH_CUSTOM_KERNEL=1 pip install -e . # 编译 native kernels

要求 macOS 15.0+ (Sequoia)、Python 3.11~3.13、Apple Silicon (M1/M2/M3/M4)。

验证安装

1
2
# 检查 native kernel 是否装上
python -c "from omlx.custom_kernels import native_kernel_status; print(native_kernel_status())"

返回 "available": True 就对了。

启动服务

1
2
3
4
5
6
7
8
9
10
11
# 默认配置(模型目录 ~/.omlx/models,端口 8000)
omlx serve --model-dir ~/models

# 打开 SSD 冷层缓存
omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache

# 限制并发数
omlx serve --model-dir ~/models --max-concurrent-requests 16

# 限制内存上限(GB)
omlx serve --model-dir ~/models --memory-guard-gb 48

启动后:

一键集成 Claude Code / Codex / OpenCode

在 Admin Dashboard 里:

  1. Integrations 页;
  2. Claude Code
  3. 复制自动生成的 ANTHROPIC_BASE_URLANTHROPIC_API_KEY
  4. 粘到你的 shell 配置里。

整个过程 30 秒。我自己的 ~/.zshrc

1
2
export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_API_KEY=omlx-local-key

之后 Claude Code 调 Anthropic API 时,请求直接打到本地 oMLX 上的某个 LLM。零云端成本,数据不出本机。

跑分布式推理(两台 Mac)

1
2
3
4
5
6
# 在两台 Mac 上都启动 omlx
# 然后在 Dashboard 的 Cluster 里:
# 1. 配 peer(对方 IP)
# 2. SSH 验证
# 3. 选择分片策略(byte-aware unequal)
# 4. Activate

实测:Qwen3.6-27B 跨两台 Mac 28.6 tok/s,单台 16.1 tok/s。+78%


五、总结:谁该用,谁该等等

适合用 oMLX 的人

  • Apple Silicon 重度用户(M1+ MacBook / Mac Studio / Mac Pro);
  • 想把本地 LLM 当生产力工具而不只是” 玩具”—— 需要稳定、需要 PagedAttention、需要连续批处理;
  • 跑长 context(>32K)的 coding / RAG /agent 场景;
  • 想用 Claude Code / OpenCode / Codex CLI 但不想上传数据到云端
  • 内存不够(128 GB 装不下 70B 模型),想两台 Mac 拼起来
  • 想要菜单栏 App + Web Dashboard 这种产品级体验,不想开终端;
  • Apache-2.0 协议,商用 OK

暂时不推荐的人

  • 没有 Apple Silicon——oMLX 必须 M1+,Intel Mac 不支持(你想买新 Mac 的理由 +1);
  • 只想” 装一个 Ollama 跑通 LLaMA-3-8B”——Ollama 还在,且更简单;
  • 想要” 开箱即用 ChatGPT 那种 UI”——oMLX 是开发者工具,不是 SaaS;
  • 不愿意折腾 MLX 模型格式 ——oMLX 跑的是 MLX 格式,不是 GGUF(要先去 HuggingFace 找 MLX 格式或者用 mlx-lm 自己转)。

局限性

  • 889 个 open issues—— 项目迭代飞快,bug 报告也飞快;
  • macOS 27 上 self-updater 在 0.6.0 之前的版本有问题 —— 第一次升级需要手动重装一次 DMG;
  • 分布式推理是 experimental——v0.6.0 才加,文档还在完善;
  • MemoryGuard 安全策略可能在你不经意时 evict 你的模型 —— 记得 pin 常用模型;
  • vendored Python 版本升级 ——LM Studio 已经踩过的坑,oMLX 后续也会遇到。

跟同类项目的对比

项目 平台 协议 PagedAttention SSD KV 菜单栏 App 分布式
oMLX Apple Silicon Apache-2.0 ✅ SwiftUI
Ollama 跨平台 MIT 仅 Mac
LM Studio 跨平台 专有
vllm-mlx Apple Silicon Apache-2.0
vllm NVIDIA Apache-2.0

—— oMLX 是唯一一个把”Apple Silicon + PagedAttention + SSD KV + 菜单栏 + 分布式” 全栈打通的

最后一句话

如果你像我一样,拿 Mac 当主力机 + 跑本地 LLM 跑得有点焦虑 ——oMLX 这种” 它就是想得比你多、还帮你点点鼠标就能用” 的项目,是真的省心。

它不是我今天误打误撞发现的小众项目 ——GitHub 18,848 stars、1,638 forks、v0.6.0 yesterday pushed—— 它已经是 Apple Silicon LLM 推理的事实标准之一。

GitHub:https://github.com/jundot/omlx

主页:https://omlx.ai

如果今天的内容对你有帮助,欢迎在博客评论区留言,或者去 GitHub 提 issue / PR—— 这个项目 issue 区活跃度很高,作者本人几乎天天回。


📌 下一篇预告:oMLX 提到了一个让我特别好奇的方向 ——Apple Silicon Metal 与 NVIDIA CUDA 异构集群(v0.6.0 release notes 里的 “Heterogeneous Metal and CUDA model pools”)。如果下一篇写这个,你会想看吗?