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/omlx。GitHub 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」这件事经历了三代产品:
第一代(2023~2024):llama.cpp + Ollama + LM Studio。简单、好装、社区庞大。但单请求、保守的 KV 缓存策略 —— 长 prompt 意味着每次从头算一遍 prefix,第一次请求 30 秒、第二次请求还是 30 秒。
第二代(2024~2025):vLLM、SGLang、TensorRT-LLM 引入 PagedAttention + 连续批处理(continuous batching)。一个 prompt 跑 100 token、另一个 1000 token,GPU 不会因为长 prompt 阻塞短 prompt,系统吞吐能拉到 20~30 倍。但全部为 NVIDIA CUDA 设计 —— 你以为 Mac 也能跑,但实际上 fork 一年没人维护、PR 堆成山。
第三代(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 Dashboard(http://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 Thinking、vision 输入(base64 / URL)、streaming usage stats、tool 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 | FastAPI Server (OpenAI / Anthropic API) |
这个架构清楚到不用解释。几个我认为特别值得拆的点:
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 | # 1. 打开 https://github.com/jundot/omlx/releases |
DMG 已经把 native custom kernels 预编译好了,GLM-5.2 / MiniMax M3 直接享受 30x 加速。
方式 B:Homebrew(CLI 玩家)
1 | brew tap jundot/omlx https://github.com/jundot/omlx |
brew services 帮你把 omlx 跑成 launchd 服务,机器重启自启。
方式 C:源码 + pip(开发者)
1 | git clone https://github.com/jundot/omlx.git |
要求 macOS 15.0+ (Sequoia)、Python 3.11~3.13、Apple Silicon (M1/M2/M3/M4)。
验证安装
1 | # 检查 native kernel 是否装上 |
返回 "available": True 就对了。
启动服务
1 | # 默认配置(模型目录 ~/.omlx/models,端口 8000) |
启动后:
- Web Dashboard: http://localhost:8000/admin
- OpenAI 兼容 API: http://localhost:8000/v1
- Anthropic 兼容 API: http://localhost:8000/v1/messages
一键集成 Claude Code / Codex / OpenCode
在 Admin Dashboard 里:
- 进 Integrations 页;
- 点 Claude Code;
- 复制自动生成的
ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY; - 粘到你的 shell 配置里。
整个过程 30 秒。我自己的 ~/.zshrc:
1 | export ANTHROPIC_BASE_URL=http://localhost:8000 |
之后 Claude Code 调 Anthropic API 时,请求直接打到本地 oMLX 上的某个 LLM。零云端成本,数据不出本机。
跑分布式推理(两台 Mac)
1 | # 在两台 Mac 上都启动 omlx |
实测: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
如果今天的内容对你有帮助,欢迎在博客评论区留言,或者去 GitHub 提 issue / PR—— 这个项目 issue 区活跃度很高,作者本人几乎天天回。
📌 下一篇预告:oMLX 提到了一个让我特别好奇的方向 ——Apple Silicon Metal 与 NVIDIA CUDA 异构集群(v0.6.0 release notes 里的 “Heterogeneous Metal and CUDA model pools”)。如果下一篇写这个,你会想看吗?