oMLX：把 KV 缓存 变成
可持久化的模型状态数据库

00摘要：九条可证伪的判断

如果只读一页，读这一页。每条判断都标注了它在本报告中的证据位置，也标注了它可能在什么条件下失效。

01定位判定：它是什么，以及它刻意不是什么

同名分支在 GitHub 上至少有四个，营销站点也在抢注相似域名。先把项目边界钉死，后面的所有性能讨论才有对象。

oMLX 是 jundot 维护的、Apache 2.0 授权的 Apple Silicon 本地推理服务。官方仓库的自我定位只有一句话：「带连续批处理与 SSD 缓存的 Apple Silicon LLM 推理服务器，可从 macOS 菜单栏管理」。支撑这一定位的是三层东西：一个 FastAPI 服务（暴露 OpenAI 与 Anthropic 兼容端点）、一套迁移自 vLLM 的分页缓存调度层、一个原生 SwiftUI 菜单栏应用。

它不是模型、不是微调框架、不是聊天客户端。它更接近于「把 vLLM 的工程模型搬到一个没有独立显存、没有 CUDA、没有多卡 NVLink 的硬件平台上」这一次移植尝试的产物。

1.1 起点与演化速度

项目于 2026 年 3 月在 Apple MLX 仓库的 GitHub Discussions 首次公开，起点是 vllm-mlx v0.1.0——一个把 vLLM 的 API 形状套在 MLX 后端上的薄封装。此后它长出了原创新实现：SSD 分层缓存、连续批处理、VLM 全分页缓存、Anthropic 兼容端点、原生 macOS 界面。仓库累计提交数已达 3,465，这个数字本身就是一条关于成熟度的重要证据（见 §09）。

1.2 与相邻项目的概念分野

最容易犯的错误，是把 oMLX 当作「Ollama 的 MLX 版」。两者共享的只有「本地 + OpenAI 兼容 API」这两点表面特征，目标函数完全不同：Ollama 优化的是首次可用时间（装完就能聊），oMLX 优化的是第 N 次请求的边际成本。

02理论根基：prefill 税，以及它为什么可以被存储掉

如果不理解 prefill 与 decode 的物理分野，就会把 oMLX 当成一个「更快的推理器」。它不是。它是一个「把已经算过的东西记住」的服务。

2.1 两个阶段的物理性质不同

Transformer 解码分两段，两段的瓶颈在硬件上是相反的：

• Prefill（预填充）：把整段 prompt 一次性前向，产出每个位置的 KV。所有 token 可以并行，矩阵乘占主导——这是算力受限（compute-bound）。在 M4 Max 上，Qwen3.8-27B dense 的 prefill 速率稳定在约 250 tok/s，这个数字几乎不随工程优化变化，它是 GPU 算力的下限。
• Decode（解码）：逐 token 生成，每步都要把全部权重从内存搬到计算单元——这是带宽受限（memory-bandwidth-bound）。所以 decode 速度基本由「内存带宽 ÷ 权重字节数」决定，与提示长度无关（只受 attention 的 O(n²) 轻微拖累）。

这个分野直接决定了一件事：你能优化的只有 prefill，decode 你优化不动。这也解释了后文所有数字的形状——为什么 oMLX 的 TTFT 能从 68.6s 降到 2.5s，而 tok/s 始终在 40–60 徘徊。

2.2 智能体请求的真实形状

一次普通聊天请求的 prompt 可能是几百 token。而一次编码智能体请求是这样的：

[system prompt]        约 2k–8k tok   ← 几乎不变
[tool definitions]     约 3k–12k tok  ← 几乎不变，但顺序敏感
[项目上下文/RAG]       约 2k–20k tok  ← 会话内不变
[对话历史]             逐轮增长
[当前用户输入]         几百 tok       ← 唯一真正新增的部分

第三方实测给了一个具体样本：把 GitHub Copilot CLI 指向本地 26B 模型，每次请求都发送 26,627 个 token 的 system + tool 定义。第一轮 0 命中，耗时 1 分 28 秒；第二轮命中 14,330（54%），耗时降到 33 秒。同一个「2+2」，同样的模型，差 2.7 倍。

这就是 prefill 税：用户为了一段从未改变的文本，每一轮都重新付一次全量计算的账。

2.3 成本模型

把首 token 延迟（TTFT）拆开，可以得到一个能指导调优的式子：

T_ttft  =  T_load        # 模型权重进入统一内存（懒加载时发生）
         +  T_warmup      # Metal kernel JIT / MLX 图优化，首次推理独有
         +  N_uncached / R_prefill   # 未命中 token 数 ÷ prefill 速率
         +  T_book   # 块哈希查找、元数据、调度开销

四项里，只有第三项与缓存直接相关，而它的分子 N_uncached 完全由客户端的 prompt 组装策略决定。这是本报告最重要的一条推论：在 oMLX 上，性能调优的主战场不在服务端配置，而在调用方的 prompt 结构。

2.4 为什么 KV 可以持久化：一个结构性红利

因果注意力有一个性质：位置 i 的 KV 只依赖位置 0..i 的 token，与后面的内容无关。这意味着 KV 是「前缀的函数」——只要前缀相同，产出的 KV 就完全相同。

于是 KV 可以被当作内容寻址的数据来处理：给定前缀，算出它的哈希，去查有没有存过；存过就直接取回，没存过就算一遍再存。这一步跨过去，KV 就从「一次会话的临时产物」变成了「可索引、可去重、可落盘、可跨进程共享的模型状态数据库」。oMLX 的全部设计都是这句话的技术展开。

反过来说，这个红利有严格前提：前缀必须逐 token 完全一致。不是语义一致，不是「差不多」，是二进制一致。这个苛刻条件，就是后面所有工程细节（块大小 4096、链式哈希、tools 敏感）的来源。

03系统架构：五层，以及一条被刻意保留的窄通道

oMLX 的架构图不复杂，但每一层都对应一个 Apple Silicon 特有的约束。读这张图的正确方式，是问「这一层如果不这么设计，会死在哪里」。

3.1 五个层次各自的「不这么设计会死在哪里」

3.2 被刻意保留的窄通道：自定义 Metal 内核

在对 Qwen3.5、GLM-5.2、MiniMax M3 这几族模型上，oMLX 提供可选的原生自定义内核（如 GLM-5.2 的融合 DSA prefill）。这不是通用优化，而是一条按模型手工开的窄通道，代价与收益都极端：

04三层 KV 缓存：一个内容寻址的状态数据库

这是整份白皮书的技术核心。如果只能记住一句话：oMLX 把 KV 当作「前缀的哈希映射」来管理，而不是当作「这次请求的临时张量」。

4.1 三级存储与各自的职责

常见的误解是「三层缓存是三级速度」。实际上三层的分工并不对称——L1 管的是元数据与活跃性，L2 管的是避免重复读盘，L3 管的是跨重启的持久性：

4.2 链式哈希：为什么不能只用 token 前缀的简单哈希

compute_block_hash(model_name, parent_hash, token_ids, extra_keys) 返回 SHA-256，关键在于 parent_hash 这一项：每个块的哈希都把它前面所有块的哈希卷进去，形成一条加密链。

这不是为了安全，是为了正确性。若只对块内 token 求哈希，那么「块 A 后面接块 B」和「块 C 后面接块 B」会因为块 B 内容相同而共享同一份 KV——但它们的注意力上下文完全不同，KV 也不同，复用直接产出错误输出。链式结构从机制上排除了这种可能：前缀不同，哈希必然不同。

代价是级联失效：只要有一个块变了，它之后所有块的哈希全变，全部失效。这解释了实测中最刺眼的那个数字——仅仅交换两个 tool 定义的顺序，命中块数从 16,384 归零。改动发生在很前面，后面 12 个块跟着一起死。

4.3 异构层：不是所有 KV 都能切块

MLX 的缓存类型并不统一。标准注意力层产出可切的 KVCache，滑动窗口模型产出 RotatingKVCache，而 Mamba / Jamba 这类状态空间层用的是 ArraysCache——它没有序列维度的分块语义，无法按块切片存储。oMLX 用一套类型注册表分流：

BoundarySnapshotSSDStore 这个设计值得单独说一句：不可切片层的状态在长 prefill 期间会持续累积占用 GPU 内存，如果不做快照，128K 上下文的 prefill 会直接把统一内存吃穿。它选择「到边界就落盘、落完立刻释放」，本质是把内存压力换成了磁盘 I/O——又一次「用存储买空间」。

4.4 工程细节：那些决定它能不能长期跑下去的东西

05调度与批处理：3.36× 背后的物理上限

连续批处理常被讲成「并发让一切变快」。在 Apple Silicon 上这个说法只对一半——它对，但只在多请求场景对；而它之所以不更快，原因在内存带宽，不在调度器。

5.1 连续批处理到底批了什么

传统静态批处理（static batching）要求一批请求全部生成完才能释放批次。一个请求生成 20 token、另一个生成 2000 token，整批就被后者拖住，短请求的槽位在空转。

连续批处理（continuous batching）改为按迭代步调度：每生成一步，完成的请求立刻退出、新请求立刻补位。oMLX 通过 Scheduler（FCFS 队列，并发数可配，默认 8）驱动 mlx-lm 的 BatchGenerator 实现这一点。

这在云 GPU 上是标配，在 Mac 本地推理市场上不是。Ollama 的请求是串行的；mlx-lm 本身没有服务层调度器。oMLX 在 macOS 上是第一个提供真实并发的选项——这个「第一」有实际价值，但价值的上限由下面的数字决定。

5.2 为什么加速比是 3.4× 而不是 8×

decode 阶段每生成一个 token，都要把全部模型权重从统一内存搬到 GPU 计算单元。8 个并发请求共享同一份权重搬运——这是批处理收益的来源。但共享之后，瓶颈就变成了带宽本身：每步的时间被「权重字节数 ÷ 带宽」锁死，与批里有几个请求无关。

所以在理想情况下，8 路并发的吞吐上限是单路的 8 倍（一次搬运服务 8 个 token），但实际上：注意力计算量随批增大而增加、KV 读取量线性增长、调度与同步开销上升。最终落在 3.4–4.1×，意味着带宽利用率从单路的约 12% 提到了约 45%——已经是很有价值的改善，但距离线性很远。

5.3 FCFS 的代价：缺少优先级是设计选择，也是缺陷

Scheduler 用先来先服务，没有优先级、没有公平份额、没有抢占。这个选择的后果是典型的队头阻塞：

• 一个 128K 上下文的慢请求排在前面，会把它后面所有请求的首 token 延迟一起拖长；
• 交互式请求（人打字等回复）与批处理请求（离线跑评测）竞争同一队列时，前者会被后者拖累；
• 没有 per-tenant 配额，一个失控的智能体外循环可以吃掉全部并发槽位。

缓解手段只有工程侧的：把批处理任务指向独立的第二个实例、或通过模型别名 + Profile 把它们在引擎层面分开。这不是优雅方案，但对单机场景够用——真正需要优先级的场景，通常也已经在考虑多机了。

06性能实证：把厂商数字与受控实验分开看

这一节只做一件事：把不同来源的证据按强度排队，找出它们在哪些结论上一致、在哪些地方互相矛盾。因为 oMLX 的性能叙事里，最有价值的事实恰恰是一条「反直觉」的。

6.1 证据分级

6.2 决定性实验：同一个请求，跑两遍

最有说服力的一组数据来自一台 M4 Max 上的 0.6.4 版本 + Qwen3.8-27B-4bit。实验设计极简：同一个请求，连发两次，只观察变化。

这组数字的完整形态是：

6.3 反直觉的发现：热路径几乎打平，差异只在重启后

一位评测者在 M4 Max 64GB 上做了 mlx-lm 与 oMLX 的对照，最初的假设是「分层缓存会在重复长前缀上碾压 mlx-lm」。结果假设被推翻：

6.4 冷启动税：必须预付款的 20 秒

oMLX 采用懒加载模型。这意味着服务启动后第一次请求要一次性付清三笔账：

三笔账的构成是：模型加载（9.7–11.9s，权重进统一内存）、首次推理预热（9–10s，Metal 内核 JIT + MLX 图优化）、全量 prefill（取决于 prompt 长度）。前两笔与 prompt 无关，是纯固定成本；第三笔才是缓存能优化掉的部分。

6.5 硬件档位的现实参考

07生态位置：Who should not use this

技术选型文档的价值，一半在「推荐什么」，另一半在「明确劝退谁」。oMLX 的适用面比它的星标数窄得多。

7.1 判断路径

7.2 应该劝退的四类用户

08部署：三种安装路径与四层配置优先级

安装方式的选择不只影响便利性，它决定了你是否拥有那 30 倍的 prefill 内核。

8.1 三条安装路径的实际差异

8.2 配置优先级：CLI > 环境变量 > settings.json > 每模型设置

四层覆盖关系清晰，但有一个容易误判的点：CLI 标志优先于持久化配置，且不写回。也就是说 omlx serve --max-concurrent-requests 16 只在本次运行生效，不会改变 ~/.omlx/settings.json，下次用默认值启动就回到 8。要让修改持久，必须在 /admin 面板里改。

8.3 安全模型：一条不许绕过的规则

oMLX 的安全设计有一条硬边界和若干软开关，理解这个分层很重要：

• 硬边界：未设置主 API key 时，服务拒绝在任何非 loopback 地址上启动。想监听 0.0.0.0，必须先有 key，或 key 与 host 一起保存。
• 软开关 1：skip_api_key_verification 会同时关闭推理与管理鉴权，因此被强制限制在 loopback 绑定下。
• 软开关 2：auth.allow_unauthenticated_inference（默认 false）允许网络绑定下的无密钥推理，但管理端点仍需主 key 或 admin 登录。这是为「局域网内多客户端调用、但管理面要锁」的场景准备的。

8.4 客户端接入

管理面板会为选定模型生成现成的配置命令，覆盖 Claude Code、OpenClaw、OpenCode、Codex、Copilot CLI、Hermes Agent、Pi、Mistral Vibe、DeepSeek Harness 等。CLI 侧可用 omlx launch list 查看本机已安装的集成。

一个实测细节值得记下：Copilot CLI 走的是 /v1/responses 端点，仓库中有注释明确指出它对 completions 端点存在问题。这类客户端差异说明「OpenAI 兼容」是个光谱而非开关——真正决定兼容性的是客户端实际调用的端点与字段，不是宣传语。

09能力边界：反证据清单

一个只列优点的技术文档没有价值。下面每一条都是「它做不到」或「它做得不够好」，且都能在实测或源码里找到依据。

10反模式清单：三类会白付成本的用法

每一条都给出症状、成因、修正动作。症状部分写得具体，是为了让你能对着自己的日志认出来。

10.1 架构层

10.2 调参层

10.3 运维层

11落地路径：五级成熟度与验收清单

从「装上试试」到「团队共享生产」，中间隔的不是配置项，而是四个具体的验证动作。

11.1 四个必须自己跑的验证

以下四条不依赖任何第三方基准，二十分钟内可完成，但它们能决定方案是否成立：

11.2 需要长期盯的三个指标

12结论：一次成功的「错位移植」

oMLX 做的事情，用一句话概括是：把一个为数据中心设计的服务模型，硬塞进了一台个人电脑，而且塞对了。

vLLM 的 PagedAttention 诞生于「显存稀缺、请求高并发、GPU 昂贵」的云环境，目的是让同一块 GPU 服务尽可能多的用户。把它搬到 Apple Silicon 上，前提全变了：没有独立显存（统一内存），没有多用户（通常一个人），GPU 不贵（已经买断了）。按常理，这套工程应该水土不服。

但它找到了一个在新环境里成立的对应物：云上稀缺的是显存，Mac 上稀缺的是「不被打断的连续计算时间」。智能体的存在制造了这个稀缺——每一轮都要求机器把两万个 token 重新算一遍，而这台机器同时还要跑 IDE、浏览器和 Docker。

于是那些在云上用来省显存的机制，在这里被用来省时间：分页是为了碎片化复用，这里是为了让不同会话共享同一段前缀；写时复制是为了并发安全，这里是为了让多个客户端读同一份缓存而不互相污染；LRU 驱逐是为了容量管理，这里是为了在 64GB 里同时放下模型、KV 和 IDE。连 SSD 落盘这个在云端几乎不存在的设计（云盘太慢），在 Mac 上反而成立——因为本地 NVMe 的随机读延迟，比重新跑一次 16K prefill 快了两个数量级。

12.1 三句话行动建议

1. 如果你的日常是 Claude Code / Cursor / Codex 指向本地模型，现在就换，收益立刻可见，而且改造成本只有一次配置。做完 §11.1 的四个验证再决定是否长期使用。
2. 如果你只是在本机聊天或跑脚本，不要换。你付出的部署复杂度与冷启动税是确定的，换回的收益是零。
3. 无论哪种情况，先花半天把自己的 prompt 组装顺序规范化。这一步的收益不依赖 oMLX——它对任何带前缀缓存的推理服务都成立，而它恰好是绝大多数团队从未做过的事。

12.2 尚待观察的三个问题

• 单维护者风险。项目由一位独立开发者维护，没有公司背书。3,465 次提交的活跃度是优点，也是单点依赖的放大器。团队采用前应评估「如果明天停更」的迁移成本——好消息是 MLX 生态本身在扩张，坏消息是这套 SSD 缓存没有等价替代。
• 跨进程 / 跨模型共享尚未出现。当前缓存绑定在单个服务实例上。如果未来能做到多个本地进程共用一个缓存池（比如 IDE 插件与 CLI 共享），收益会再上一个量级。这是最值得期待的方向。
• 基准数据的独立性。目前几乎所有性能数字都来自维护者自测或单篇第三方评测，缺少多环境、多负载的交叉验证。SSD 恢复路径在慢速盘、低内存机器上的表现尤其缺乏数据。

13参考来源

按证据类型分组。项目自述与第三方实测严格分列，厂商基准单列，便于读者按需回溯。

一手项目资料

• 代码与文档：github.com/jundot/omlx —— README（架构段、CLI 段、模型支持表、致谢）、docs/admin-api.md。注意 GitHub 上存在多个同名 fork（longfei12k/omlx、jgranie/omlx 等），内容为镜像，非原始项目。
• 源码级机制：DeepWiki 对 jundot/omlx 的索引页，关键文件 omlx/cache/paged_cache.py（块哈希 compute_block_hash）、omlx/cache/prefix_cache.py（BlockAwarePrefixCache）、omlx/cache/paged_ssd_cache.py（Hot Cache 与 _write_safetensors_no_mx）、omlx/cache/boundary_snapshot_store.py（BoundarySnapshotSSDStore）、omlx/cache/type_registry.py、omlx/cache/stats.py、omlx/server.py。本报告的三层缓存与类型注册表描述均据此。
• 官方站点：omlx.ai（作者维护，含功能说明与 /benchmarks 社区提交页）。相关内容需与 README 交叉核对。

第三方受控实验（证据强度最高）

• 缓存命中对照实验：EOGEE《Qwen3.8-27B 本地高速部署方案（Mac Studio M4 Max / oMLX）》，oMLX 0.6.4 + Qwen3.8-27B-4bit。提供 16.7K 请求的冷/热 TTFT、命中块数、tools 顺序敏感性、块粒度 4096 与 TTFT 三层根因分解。本报告 §06.2 全部数字与 §02.3 的成本模型据此。
• mlx-lm vs oMLX 对照：daily.dev《mlx-lm vs oMLX: I Was Wrong About the Winner》，Mac Studio M4 Max 64GB。提供热态 prefill 3.4/3.6s、decode 22–25 tok/s、重启后 17s/7.2s 三组关键对照，以及四个评测陷阱（mlx-lm 的 prompt 缓存、缓冲输出、oMLX 懒加载、SSD 缓存污染冷启动测量）。本报告 §06.3 据此。
• 冷启动分解与客户端实测：lilting.ch《oMLX 0.3.9.dev2 tested on M1 Max 64GB》。提供卸载 0.9s、加载 9.7–11.9s、首次推理预热 9–10s 的分解，以及 Copilot CLI 26.6K token 请求 88s → 33s（54% 命中）的实测。§06.4 与 §08.4 据此。
• RAG 场景 TTFT 表：Stochastic Sandbox《omlx: Run Local LLMs on Apple Silicon with a RAG Customer Support App》，M3 Max 128GB + Qwen3-8B-4bit，三种 prompt 长度的冷/热 TTFT 与 tok/s。

厂商自测基准

• 吞吐与批处理：官方基准表（M3 Ultra 512GB），Qwen3.5-122B-A10B-4bit、Qwen3-Coder-Next-8bit、MiniMax-M2.5-8bit、GLM-5-4bit 的单请求与 1×–8× 并发数据（pp1024 / tg128，无缓存复用）。本报告图 4 据此。
• 社区提交基准：omlx.ai/benchmarks，含 M4 Max 40c 128GB 上 Qwen3.8-Flash-Next 各量化与各上下文的 PP/TG 数据（1k–128k）。表 7 部分行据此。
• 内核性能：README 安装段注释，GLM-5.2 融合 DSA prefill 在 M3 Ultra 上 845 vs 约 29 tok/s（约 30×），需完整 Xcode 与 Metal toolchain。

背景资料

• MLX 框架机制：Apple MLX 的统一内存、惰性求值、动态图、Metal 后端与 mx.compile 融合机制（用于 §02.1 的 prefill/decode 物理性质分析）。
• Mac 推理栈全景：多篇 2026 年横评（Ollama 的 MLX runner 演进、LM Studio 双后端、llama.cpp 的 slot 并发、mlx-lm 的无服务层），用于表 1 的对比校准。
• 项目评测与背景：PromptQuorum 的 oMLX 评测（项目起源、维护者背景、fork 泛滥情况）、RunAIHome 的 Apple Silicon 综述（边界判断、硬件档位建议）。