oMLX：macOS菜单栏管理13k星的LLM推理服务器，连续批处理+SSD缓存

“我试过的每个 LLM 服务器都要我在便利性和控制性之间二选一。我想把常用模型常驻内存，把重的模型自动 swap 到 SSD，还能设置上下文限制——全部从菜单栏管理。这就是我造 oMLX 的原因。”

一句话定位

oMLX 是一个专为 Apple Silicon 优化的 LLM 推理服务器，核心卖点：

• 连续批处理（Continuous Batching）：并发请求高效处理
• 热冷 KV 缓存：RAM 常驻 + SSD 分级缓存，上下文跨请求复用
• 菜单栏管理：零配置开机自启，一个图标管全部

当前 GitHub ⭐ 13.5k，Python 实现，macOS 专属，Apache 2.0 许可证。

解决什么问题

在 Apple Silicon 上跑本地 LLM 已经有 mlx-lm 和 Ollama 这样的工具。oMLX 的差异化在于企业级推理特性：

连续批处理

传统推理服务器按顺序处理请求。连续批处理（Continuous Batching）允许不同请求共享 GPU 计算周期，显著提高并发吞吐量。

oMLX 基于 mlx-lm 的 BatchGenerator 实现，可配置最大并发数（通过 CLI 或管理面板）。

热冷 KV 缓存

这是 oMLX 最独特的设计。它受 vLLM 启发，实现了两级 KV 缓存：

┌─────────────────────────────────────────────┐
│  Hot Tier (RAM)                              │
│  常用模型的 KV cache 常驻内存，访问零延迟    │
├─────────────────────────────────────────────┤
│  Cold Tier (SSD)                             │
│  当 hot 满了，block 被 offload 到 SSD        │
│  下次请求用到这段 prefix 时，从 SSD 恢复      │
│  即使服务重启，cache 依然有效                │
└─────────────────────────────────────────────┘

这解决了什么问题？

• 上下文复用：同一个对话的上下文只需计算一次，后续请求复用 KV cache
• 跨请求复用：多轮对话中，前面的轮次的计算结果不丢失
• 持久化：服务重启不丢失 cache，配合 Claude Code 等工具时特别有用

Claude Code 优化

这是 oMLX 的一个细分但重要的功能。小上下文模型配合 Claude Code 时，需要正确处理 context scaling。oMLX 会：

• 缩放报告的 token 数量，使 auto-compact 在正确时机触发
• SSE keep-alive 防止长 prefill 期间的读取超时

核心功能

支持的模型类型

所有模型在目录下自动发现，无需手动注册。

多模型同时服务

一个 oMLX 实例可以同时加载多个不同类型的模型：

• LRU 驱逐：内存不足时自动卸载最少使用的模型
• 手动加载/卸载：管理面板一键操作
• 模型固定（Pin）：常用模型保持常驻
• Per-model TTL：设置空闲超时，超时自动卸载
• 总内存限制：默认 系统RAM - 8GB，防止系统级 OOM

管理面板

内置 Web UI（/admin），功能包括：

• 实时监控（显存/内存使用、请求延迟）
• 模型管理（加载/卸载/固定）
• 内置聊天（支持历史记录、模型切换、深色模式）
• 模型下载器（HuggingFace 直接下载）
• Benchmark 工具
• Claude Code / OpenClaw / OpenCode / Codex / Pi 一键集成配置

支持英/韩/日/中/俄五种语言，所有 CDN 依赖已 vendored，完全离线可用。

安装方式

macOS App（推荐）

# 下载 releases 中的 .dmg
# 拖到 Applications 即可
# 支持内置自动更新

Homebrew

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

# 升级
brew update && brew upgrade omlx

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

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

从源码

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .          # 核心
pip install -e ".[mcp]"   # MCP 支持

要求：macOS 15.0+（Sequoia）、Python 3.10+、Apple Silicon（M1/M2/M3/M4）

快速开始

macOS App

1. 启动 oMLX
2. Welcome 引导：选择模型目录 → 启动服务 → 下载第一个模型
3. 连接 OpenClaw/OpenCode/Cody 等工具

CLI

# 启动服务
omlx serve --model-dir ~/models

# 服务发现目录下所有模型（LLM/VLM/Embedding/Reranker）
# OpenAI 兼容接口：http://localhost:8000/v1

# 内置聊天 UI
# 访问 http://localhost:8000/admin/chat

与 Claude Code 集成

# 在管理面板（/admin/integrations）一键配置 Claude Code
# 或手动设置环境变量
export OPENAI_BASE_URL=http://localhost:8000/v1
export OPENAI_API_KEY=any

技术架构

核心技术栈

• 推理引擎：mlx-lm（Apple 的 MLX 框架）
• 批处理：mlx-lm BatchGenerator
• 缓存：自定义 block-based KV cache（hot RAM + cold SSD）
• API：OpenAI 兼容（/v1/models, /v1/chat/completions 等）
• 前端：Vue.js（管理面板）

KV Cache 实现细节

Block Size: 固定大小（如 64 tokens/block）
Copy-on-Write: 相同 prefix 的请求共享 block 引用
Prefix Sharing: 多请求共用相同 system prompt 的 cache
LRU Eviction: Least Recently Used 驱逐策略

当 hot tier（RAM）满了，Least Recently Used 的 block 被压缩写入 SSD（safetensors 格式）。下次请求需要这段 prefix 时，直接从 SSD 读取并恢复到 RAM。

内存管理

# 总内存限制配置（默认：系统 RAM - 8GB）
omlx serve --max-memory 48GB  # 手动设置

# 或在管理面板调节
# 系统会自动阻止 OOM

与同类工具的比较

oMLX 的定位是"Apple Silicon 原生 + vLLM 级别的企业特性"。

适用场景

✅ 强项场景：

• Apple Silicon 用户需要本地跑 LLM（隐私/成本/离线）
• 多用户/多模型并发服务（连续批处理提升吞吐）
• 长上下文多轮对话（KV cache 复用）
• Claude Code / OpenClaw 等工具的本地模型后端
• 需要管理面板而非命令行的团队

❌ 不适合：

• Linux 或非 Apple 硬件（专为 macOS 设计）
• 追求极致单请求性能的独立部署（llama.cpp 更快）
• 需要 Windows 支持的场景

总结

oMLX 填补了 Apple Silicon 本地 LLM 推理的一个空白：把 vLLM 的企业级特性（连续批处理、分级缓存）带到了 macOS 上，同时保持了零配置的易用性。

对于已经在 Apple Silicon 上工作、且需要用本地模型跑 Claude Code 或其他 AI 编程工具的开发者，oMLX 是一个自然的升级选择——KV cache 持久化和 Claude Code 优化这两点，是它真正的差异化价值。

项目信息

• GitHub：jundot/omlx ⭐ 13.5k
• 语言：Python
• 平台：macOS 15.0+ Apple Silicon 专用
• 许可证：Apache 2.0
• 官网：omlx.ai
• 官方 Benchmark：omlx.ai/benchmarks