omlx

概述

oMLX 是一款面向 Apple Silicon 优化的本地大语言模型推理引擎。它通过持续批处理与分层 KV 缓存，让用户在 Mac 上既能保留日常模型常驻内存，又能按需自动加载较大模型，并从菜单栏直接管理这一切。项目的核心动机是：现有 LLM 服务在易用性与可控性之间难以兼顾，oMLX 通过持久化 KV 缓存（热内存层 + 冷 SSD 层）解决了会话中途上下文变化后历史缓存失效的问题，从而让本地 LLM 在 Claude Code 等真实编码场景中具备实用性。

安装方式

macOS 应用

从 Releases 下载 .dmg，拖入 Applications 即可。应用内置自动更新，并附带 ~/.omlx/bin/omlx CLI 桥接脚本，便于终端命令与 Apple Shortcuts 控制应用管理的服务。

Homebrew

brew tap jundot/omlx https://github.com/jundot/omlx
brew install jundot/omlx/omlx
omlx start  # 作为后台服务运行，崩溃后自动重启

如需原生自定义内核（GLM-5.2 / MiniMax M3），需安装 Xcode 后使用 brew install jundot/omlx/omlx --HEAD --with-custom-kernel。

源码构建

需要 macOS 15.0+、Python 3.11–3.13、Apple Silicon（M1 至 M5）：

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .          # 仅核心
pip install -e ".[mcp]"   # 含 MCP 支持
OMLX_WITH_CUSTOM_KERNEL=1 pip install -e .  # 构建原生内核

快速上手

启动服务后，任何 OpenAI 兼容客户端均可连接 http://localhost:8000/v1，内置聊天界面位于 http://localhost:8000/admin/chat。服务会自动从子目录中发现 LLM、VLM、嵌入模型与重排序模型。

omlx start    # 启动托管后台服务
omlx stop
omlx restart
omlx serve --model-dir ~/models  # 前台运行

Homebrew 服务模式下，日志分别写入 $(brew --prefix)/var/log/omlx.log 与 ~/.omlx/logs/server.log。

核心特性

分层 KV 缓存

借鉴 vLLM 的块式 KV 缓存管理，支持前缀共享与写时复制。缓存分两层运作：

• 热层（RAM）：高频访问块常驻内存。
• 冷层（SSD）：热缓存写满后块以 safetensors 格式卸载到 SSD；下次匹配前缀的请求可直接从磁盘恢复，无需重算，服务器重启后仍生效。

持续批处理

通过 mlx-lm 的 BatchGenerator 处理并发请求，最大并发数可通过 CLI 或管理面板配置。

多模型服务

在同一服务器中混合加载 LLM、VLM、嵌入与重排序模型，配备 LRU 淘汰、手动加载/卸载、模型固定、按模型 TTL 空闲超时，以及进程级内存上限保护（默认系统内存减去 8 GB）。

Claude Code 优化

支持上下文缩放，使较小上下文模型在 Claude Code 中触发自动压缩的时机更准确；SSE 保活机制避免长 prefill 期间读超时。

实验性多 Mac 推理

源码构建支持将单一模型按不等内存拆分到多台 Mac 上，通过 MLX 流水线并行配合 Ring 或 Thunderbolt RDMA/JACCL 通信。集群面板提供只读节点发现、严格 SSH/运行时校验、按字节感知的不等分片规划、实测算力/链路再平衡、动态余量执行调优、激活控制以及实时分片与性能映射。

视觉语言模型

复用与 LLM 相同的持续批处理与分层 KV 缓存栈，支持多图对话、base64/URL/文件图像输入，以及含视觉上下文的工具调用。OCR 模型（DeepSeek-OCR、DOTS-OCR、GLM-OCR）可被自动识别并使用优化提示词。

每模型配置

通过管理面板即时配置采样参数、聊天模板参数、TTL、模型别名、模型类型覆盖等。Profile 机制允许保存命名配置包并切换，配置文件甚至可以以 <model>:<profile> 形式作为独立模型对外暴露，复用同一引擎且不额外占用内存。

模型支持

将 --model-dir 指向包含 MLX 格式子目录的文件夹即可，模型按类型自动检测，也可直接在管理面板中搜索下载 HuggingFace 上的 MLX 模型。支持类型包括：LLM（任何 mlx-lm 支持的模型）、VLM（Qwen3.5、GLM-4V、Pixtral 等）、OCR（DeepSeek-OCR、DOTS-OCR、GLM-OCR）、嵌入（BERT、BGE-M3、ModernBERT）、重排序（ModernBERT、XLM-RoBERTa）。

CLI 配置

omlx serve --model-dir ~/models --memory-guard safe        # 选择内存保护档位
omlx serve --model-dir ~/models --memory-guard-gb 48       # 自定义上限
omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache  # 启用 SSD 缓存
omlx serve --model-dir ~/models --hot-cache-max-size 20%   # 热缓存占比
omlx serve --model-dir ~/models --max-concurrent-requests 16
omlx serve --model-dir ~/models --mcp-config mcp.json      # MCP 工具
omlx serve --model-dir ~/models --hf-endpoint https://hf-mirror.com
omlx serve --model-dir ~/models --api-key your-secret-key  # API 鉴权

所有设置亦可在 /admin 管理面板中配置，持久化至 ~/.omlx/settings.json，CLI 参数优先级最高。

API 兼容性

提供 OpenAI 与 Anthropic API 的直接替代，支持流式用量统计（stream_options.include_usage）、Anthropic 自适应思考、视觉输入（base64、URL）。主要端点包括 /v1/chat/completions、/v1/completions、/v1/messages、/v1/embeddings、/v1/rerank、/v1/models。

技术架构

FastAPI Server（OpenAI / Anthropic API）
    ├── EnginePool（多模型、LRU 淘汰、TTL、手动加载/卸载）
    │   ├── BatchedEngine（LLM，持续批处理）
    │   ├── VLMEngine（视觉语言模型）
    │   ├── EmbeddingEngine
    │   └── RerankerEngine
    ├── ProcessMemoryEnforcer（总内存限制、TTL 检查）
    ├── Scheduler（FCFS，可配置并发）
    │   └── mlx-lm BatchGenerator
    └── Cache Stack
        ├── PagedCacheManager（GPU，块式，CoW，前缀共享）
        ├── Hot Cache（内存层，写回）
        └── PagedSSDCacheManager（SSD 冷层，safetensors 格式）

开发与构建

CLI 服务开发：pip install -e ".[dev]" 后运行 pytest -m "not slow"。macOS 应用位于 apps/omlx-mac/，需 Xcode 26.5+ 与 Python 3.11+。首次冷构建约需 10–20 分钟（venvstacks Python 层组装），后续构建复用缓存约 4 分钟完成：

apps/omlx-mac/Scripts/build.sh release
apps/omlx-mac/Scripts/build.sh release --rebuild-donor      # 强制重建 Python 层
apps/omlx-mac/Scripts/build.sh release --with-custom-kernel # 含原生内核

许可证

Apache 2.0。