把语言化为行动，比把行动化为语言困难得多。——高尔基

https://github.com/jundot/omlx

oMLX：住在你 Mac 里的“本地大模型管家”，从菜单栏开始把推理安排得明明白白

如果你的 Mac 是一座城市，那么本地大模型推理就是城市里最忙的那条主干道：车流（请求）一多就堵，红绿灯（调度）一乱就卡，停车位（显存/内存）不够就直接“爆仓”。
而 oMLX 更像是这座城市里一位穿着制服、手拿对讲机的交通指挥官——不光把路修好了，还把 连续批处理（continuous batching）、冷热分层 KV Cache（tiered KV caching）、多模型共存与自动腾挪，统统打包成一个你能从菜单栏就能管理的优雅系统。

它的自我介绍很直白也很骄傲：

LLM inference, optimized for your Mac
Continuous batching and tiered KV caching, managed directly from your menu bar.

你不用在“方便”和“可控”之间二选一，oMLX 说：都给你。

oMLX 想解决的那种“本地推理烦恼”

oMLX 有点像一个有洁癖的管理员：它不喜欢你一会���开一个服务、一会儿换一个模型、一会儿手动清缓存、一会儿又为了上下文长度纠结到深夜。

它更想要这样的生活方式：

  • 日常模型 常驻内存（你想用就秒回）
  • 更重的模型 按需自动切换
  • 上下文限制 可控（而且最好不用你到处改配置）
  • 还有最关键的：缓存要能复用，不要每次都从头算到尾

于是它用自己的方式说话：
“让我来管。我把 KV cache 分成热的和冷的，让它们各司其职；我把并发请求排好队，让它们一起上车；我把所有按钮塞进菜单栏，让你不必再和终端纠缠。”

安装：让 oMLX 走进你的 Mac（它很会搬家）

方式一：macOS App（最像“把它请进家里”）

从 GitHub Releases 下载 .dmg，拖进 Applications 就完成。
而且它还带 in-app auto-update：以后升级一键完成，它会自己收拾行李，不麻烦你。

方式二：Homebrew（让它在你系统里“入编制”）

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

# Upgrade to the latest version
brew update && brew upgrade omlx

# Run as a background service (auto-restarts on crash)
brew services start omlx

# Optional: MCP (Model Context Protocol) support
/opt/homebrew/opt/omlx/libexec/bin/pip install mcp

它甚至会主动表态：“我可以做后台服务，还能崩了自动重启。”
这语气像极了那种靠谱同事：不吵不闹，但永远在线。

方式三：From Source（如果你想和它一起写代码、一起成长）

1
2
3
4
git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .          # Core only
pip install -e ".[mcp]"   # With MCP (Model Context Protocol) support

硬性要求它也说得很清楚：

  • macOS 15.0+ (Sequoia)
  • Python 3.10+
  • Apple Silicon（M1/M2/M3/M4）

快速启动：它最喜欢的开场白

1）macOS App：三步欢迎仪式

你从 Applications 打开 oMLX，它的 Welcome 屏幕会带你走完三件事：

  1. 选择模型目录（model directory）
  2. 启动 server
  3. 下载第一个模型

然后它会说：好了，坐下吧，我们开始聊天。

2）CLI：一句命令把它叫醒

1
omlx serve --model-dir ~/models

它会自动从子目录里发现各种角色（它的“员工”们）：

  • LLMs
  • VLMs
  • embedding models
  • rerankers

并且任何 OpenAI-compatible client 都能连到：

  • http://localhost:8000/v1

它不像某些服务那样“你要先配这个再改那个”，oMLX 更像在说：
“你先把模型放好，剩下的我来。”

Homebrew Service：让 oMLX 成为你电脑里的“长期工”

如果你用 Homebrew 安装，它还能当一个受管理的后台服务：

1
2
3
4
brew services start omlx    # Start (auto-restarts on crash)
brew services stop omlx     # Stop
brew services restart omlx  # Restart
brew services info omlx     # Check status

它默认会用 零配置启动：

  • 模型目录：~/.omlx/models
  • 端口：8000
  • 命令：omlx serve

要自定义也简单：

  • 用环境变量（OMLX_MODEL_DIR, OMLX_PORT, …）
  • 或者直接用 omlx serve --... 的参数覆盖

日志它也安排得井井有条，像在给你留“工作日报”：

  • Service log：$(brew --prefix)/var/log/omlx.log（stdout/stderr）
  • Server log：~/.omlx/logs/server.log（结构化应用日志）

它的核心能力：oMLX 的“人格魅力”到底在哪

oMLX 不是只会“跑模型”，它更像一个系统级别的运营者：懂调度、懂缓存、懂资源管理，还懂得如何让你不被这些细节拖累。

官方一句话总结它的舞台范围：

Supports text LLMs, vision-language models (VLM), OCR models, embeddings, and rerankers on Apple Silicon.

下面这些能力，基本就是它的“拿手好戏”。

Admin Dashboard：它的控制室在 /admin

oMLX 给自己配了一个 Web 控制台：/admin
你可以在这里做实时监控、模型管理、聊天、benchmark、还有每个模型的独立设置。

它还很国际化：

  • English, Korean, Japanese, Chinese, Russian
    而且 所有 CDN 依赖都 vendored ——它不喜欢把命运交给网络波动。

它像在说：
“我不仅能跑，我还要让你看到我怎么跑。”

视觉语言模型（VLM）：它不仅会说，还会看

oMLX 让 VLM 也享受同一套“豪华待遇”：

  • continuous batching
  • tiered KV cache

并支持：

  • multi-image chat
  • base64 / URL / file image inputs
  • tool calling with vision context

甚至 OCR 模型也能上场（例如 DeepSeek-OCR、DOTS-OCR、GLM-OCR），它像一个认真阅读图片的小秘书：
“你给我图，我给你字。”

分层 KV Cache（Hot + Cold）：它把记忆分成“热的”和“冷的”

oMLX 的 KV cache 管理灵感来自 vLLM：
block-based、支持 prefix sharing、还有 Copy-on-Write。

它把缓存分成两个世界：

  • Hot tier (RAM)：常用块留在内存，取用飞快
  • Cold tier (SSD)：热缓存满了就把块写到 SSD（safetensors 格式）；下一次遇到相同前缀，直接从磁盘恢复，不用重新算

它的语气就像在给自己配一个“记忆宫殿”：

  • 热记忆：随用随取
  • 冷记忆：归档保存
  • 需要时：立刻唤醒

更关键的是：它强调一种很“人类”的体验——即便对话中途上下文变化，过去的上下文也能继续被缓存、复用。它并不想让你每次都从零开始。

Continuous Batching：它会把请求“拼车”送上 GPU

并发请求多的时候，oMLX 不让它们互相踩踏，而是用 mlx-lm 的 BatchGenerator 做连续批处理。

最大并发请求数还能配置（CLI 或 admin panel）。

它像一位会排队的领班：
“别抢，一个个来；但我会把你们打包一起上车。”

Claude Code Optimization：它也懂“上下文尺度感”

oMLX 对 Claude Code 有专门优化：

  • 支持 context scaling：让小上下文模型在 Claude Code 场景里更合理地触发 auto-compact
  • SSE keep-alive：减少 read timeout

它像在说：
“我知道你要用它写代码，我帮你把那些细小却致命的卡顿都抚平。”

Multi-Model Serving：它擅长在同一个屋檐下安顿很多模型

oMLX 能在一个 server 里同时管理：

  • LLMs
  • VLMs
  • embedding models
  • rerankers

而且它的管理方式很像一个有经验的宿舍管理员：

  • LRU eviction：内存紧张就自动把最久没用的模型请出去
  • Manual load/unload：在 admin 面板点一下就能加载/卸载
  • Model pinning：常用模型钉住，永不搬走
  • Per-model TTL：每个模型设空闲超时，到了就自动卸载
  • Process memory enforcement：总内存上限（默认 system RAM - 8GB），防止系统 OOM

它不爱浪费，也不让你操心。

Per-Model Settings：每个模型都有自己的“性格面板”

你可以在 admin panel 为每个模型设置：

  • sampling parameters
  • chat template kwargs
  • TTL
  • model alias
  • model type override
  • 等等

而且 立即生效，无需重启服务。

它还支持两件很实用的事：

  • Model alias：自定义 API 可见名称
    /v1/models 返回 alias，请求也接受 alias 和目录名
  • Model type override：手动指定它到底是 LLM 还是 VLM（不必依赖自动检测）

它像在说：
“你不用把所有模型当成一类人，我允许它们各自精彩。”

Built-in Chat：它自己也能陪你聊两句

在 admin panel 就能直接和任何已加载模型聊天，支持：

  • conversation history
  • model switching
  • dark mode
  • reasoning model output
  • VLM/OCR 的 image upload

这时候它不像基础设施，更像一个可直接使用的产品。

Model Downloader：它会自己去 HuggingFace 把模型“请回来”

你可以在 admin dashboard 里搜索、查看模型卡片、核对文件大小，然后一键下载 MLX 模型。

它像一个认真负责的采购：
“型号我帮你找，价格（体积）我帮你看，按一下我就把它送到仓库。”

Integrations：它喜欢“一键就好”

OpenClaw、OpenCode、Codex、Pi……
这些都可以在 admin dashboard 一键配置，不需要你手动改配置文件。

它对“重复劳动”有点不耐烦：
“别再复制粘贴了，你点一下，我来写。”

Performance Benchmark：它还会给自己做体检

一键 benchmark，测：

  • prefill (PP) tokens/s
  • text generation (TG) tokens/s

还支持 partial prefix cache hit testing，让性能数字更贴近真实对话场景。

它像一位工程师式的运动员：
“我不只说我快，我给你测给你看。”

macOS Menubar App：它把“掌控感”藏进菜单栏

这是它最迷人的地方之一：
原生 PyObjC menubar app（不是 Electron）。

你可以在不打开终端的情况下：

  • Start / Stop server
  • Monitor server
  • 看 serving stats（而且能跨重启保留）
  • 崩了自动重启
  • 还带 in-app update

它像一位沉默的管家，住在菜单栏里，不打扰你，却随时待命。

API Compatibility：它会说 OpenAI，也会说 Anthropic

oMLX 作为 API 层面，主打“替换成本低”：

  • OpenAI API 兼容
  • Anthropic API 兼容
  • 支持 streaming usage stats：stream_options.include_usage
  • 支持 Anthropic adaptive thinking
  • 支持 vision inputs（base64、URL）

它把自己的能力写成了清晰的路标：

Endpoint Description
POST /v1/chat/completions Chat completions (streaming)
POST /v1/completions Text completions (streaming)
POST /v1/messages Anthropic Messages API
POST /v1/embeddings Text embeddings
POST /v1/rerank Document reranking
GET /v1/models List available models

它像在对你说：
“你原来怎么调 OpenAI / Anthropic，现在也几乎可以怎么调我。”

Tool Calling & Structured Output：它懂“工具调用”这门手艺

oMLX 支持 mlx-lm 里所有 function calling 形式、JSON schema validation、以及 MCP tool integration。
当然，它也会强调前提：模型的 chat template 需要支持 tools 参数。

它还整理了各家模型可能使用的 tool call 输出格式，像一个见多识广的翻译官：

Model Family Format
Llama, Qwen, DeepSeek, etc. JSON <tool_call>
Qwen3.5 Series 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>

它像在说：
“你们输出格式不同没关系，我能认得出来。只要你愿意调用工具，我就愿意接住你。”

模型目录（Models）：给它一个“仓库”，它就能开工

你只需要把 --model-dir 指向一个包含 MLX 格式模型子目录的文件夹。

它还支持两层组织结构，例如：mlx-community/model-name/。

示例结构如下：

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

模型会被自动按类型检测，你也可以直接在 admin dashboard 下载模型。

支持类型与来源也写得很明白：

Type Models
LLM Any model supported by mlx-lm
VLM Qwen3.5 Series, GLM-4V, Pixtral, and other mlx-vlm models
OCR DeepSeek-OCR, DOTS-OCR, GLM-OCR
Embedding BERT, BGE-M3, ModernBERT
Reranker ModernBERT, XLM-RoBERTa

CLI Configuration：它的“性格参数”都在这里

oMLX 的配置既可以在 /admin 配，也可以用 CLI flags。
它还会把设置持久化到：

  • ~/.omlx/settings.json

并且声明：CLI flags 优先级更高。

下面这些命令像是它递给你的“调教手册”，非常直接：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Memory limit for loaded models
omlx serve --model-dir ~/models --max-model-memory 32GB

# Process-level memory limit (default: auto = RAM - 8GB)
omlx serve --model-dir ~/models --max-process-memory 80%

# Enable SSD cache for KV blocks
omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache

# Set in-memory hot cache size
omlx serve --model-dir ~/models --hot-cache-max-size 20%

# Adjust max concurrent requests (default: 8)
omlx serve --model-dir ~/models --max-concurrent-requests 16

# With MCP tools
omlx serve --model-dir ~/models --mcp-config mcp.json

# HuggingFace mirror endpoint (for restricted regions)
omlx serve --model-dir ~/models --hf-endpoint https://hf-mirror.com

# API key authentication
omlx serve --model-dir ~/models --api-key your-secret-key
# Localhost-only: skip verification via admin panel global settings

它像一个成熟的系统工具：
“你想要可控？给你。你想要省心？也给你。”

架构一瞥：它的“内心结构”其实很工整

它把自己的结构折叠在 README 的 Architecture 里，像把心脏剖面图递给好奇的人：

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)

你会发现它不是“临时拼凑”的玩具，而是很明确地在做一件事：
把本地推理变成可运营、可管理、可持续的服务。

开发：如果你想和它一起“卷性能、卷体验”

CLI Server 开发

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

macOS App 打包

要求：

  • Python 3.11+
  • venvstacks：pip install venvstacks

构建命令：

1
2
3
4
5
6
7
8
9
10
cd packaging

# Full build (venvstacks + app bundle + DMG)
python build.py

# Skip venvstacks (code changes only)
python build.py --skip-venv

# DMG only
python build.py --dmg-only

它的 App bundle 结构也讲得清清楚楚，像在说：
“我不是黑盒，你想拆开看就拆开看。”

贡献与许可：它欢迎你来一起把它变得更好

它欢迎：

  • Bug fixes and improvements
  • Performance optimizations
  • Documentation improvements

许可证：Apache 2.0

它的态度像个开源项目应有的样子：
“不用客气，来吧，一起把本地推理这件事做得更舒服。”

尾声：oMLX 的气质，是把“本地推理”变成一种日常

oMLX 并不想成为你生活里的“又一个工具”。
它更像一个常驻的伙伴：懂你的 Mac、懂你的资源、懂你的模型，也懂你想要的那种稳定、可控、顺滑的本地推理体验。

它住在菜单栏里，轻声说：

  • 需要我？我在。
  • 模型多？我管。
  • 并发高？我排。
  • 缓存重？我分层存。
  • 你只要安心用就好。

而这，大概就是 oMLX 最吸引人的地方。