oMLX

LLM 推理，专为您的 Mac 优化
连续批处理与分层 KV 缓存，直接通过菜单栏管理。

junkim.dot@gmail.com · https://omlx.ai/me

安装 · 快速入门 · 功能 · 模型 · CLI 配置 · 基准测试 · oMLX.ai

English · 中文 · 한국어 · 日本語

我尝试过的每一种 LLM 服务器，都让我在便利性和控制权之间做出选择。我希望将常用模型常驻内存，按需自动交换较重的模型，设置上下文限制——并且这一切都能通过菜单栏来管理。

oMLX 在热态内存层和冷态 SSD 层之间持久化 KV 缓存——即使对话过程中上下文发生变化，所有历史上下文仍会保留在缓存中并可在后续请求中重复使用，这使得本地 LLM 在实际编码工作中与 Claude Code 等工具结合使用时变得切实可行。这就是我构建它的原因。

安装

macOS 应用程序

从 Releases 下载 .dmg 文件，将其拖入 Applications 文件夹即可完成安装。该应用程序包含应用内自动更新功能，因此未来的升级只需点击一下。请注意，macOS 应用程序不会安装 omlx CLI 命令。如需在终端中使用，请通过 Homebrew 或源码进行安装。

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 应用程序

从 Applications 文件夹启动 oMLX。欢迎界面会引导您完成三个步骤——模型目录、启动服务器以及首次下载模型。仅此而已。要连接 OpenClaw、OpenCode 或 Codex，请参阅 集成。

CLI

omlx serve --model-dir ~/models

服务器会自动从子目录中发现 LLM、VLM、嵌入模型和重新排序器。任何兼容 OpenAI 的客户端都可以连接到 http://localhost:8000/v1。内置聊天界面也可在 http://localhost:8000/admin/chat 访问。

Homebrew 服务

如果您通过 Homebrew 安装了 oMLX，可以将其作为受管后台服务运行：

brew services start omlx    # 启动（崩溃后自动重启）
brew services stop omlx     # 停止
brew services restart omlx  # 重启
brew services info omlx     # 查看状态

该服务会以零配置默认值运行 omlx serve（~/.omlx/models, 端口 8000）。如需自定义，可设置环境变量（OMLX_MODEL_DIR、OMLX_PORT 等），或运行一次 omlx serve --model-dir /your/path，以将设置保存到 ~/.omlx/settings.json。

日志会写入两个位置：

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

功能

支持文本 LLM、视觉-语言模型（VLM）、OCR 模型、嵌入模型和重新排序器，运行于 Apple Silicon 平台。

管理仪表盘

位于 /admin 的 Web UI，用于实时监控、模型管理、聊天、基准测试以及每个模型的设置。支持英语、韩语、日语和中文。所有 CDN 依赖项均已打包，可完全离线运行。

视觉-语言模型

VLM 可以使用与文本 LLM 相同的连续批处理和分层 KV 缓存架构运行。支持多图像聊天、base64/URL/文件形式的图像输入，以及带有视觉上下文的工具调用。OCR 模型（DeepSeek-OCR、DOTS-OCR、GLM-OCR）会自动检测，并采用优化后的提示词。

分层 KV 缓存（热 + 冷）

基于 vLLM 的块级 KV 缓存管理，支持前缀共享和写时复制。缓存分为两层：

• 热层（RAM）：频繁访问的块会保留在内存中，以便快速访问。
• 冷层（SSD）：当热缓存满时，块会被卸载到 SSD，以 safetensors 格式存储。下次有匹配前缀的请求时，这些块会从磁盘恢复，而不是从头开始重新计算——即使在服务器重启后也是如此。

连续批处理

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

Claude Code 优化

支持上下文缩放，以便使用较小上下文的模型运行 Claude Code。它会调整报告的 token 数量，使自动压缩触发时机恰当，并通过 SSE keep-alive 防止长时间预填充期间出现读取超时。

多模型服务

在同一服务器中加载大语言模型（LLM）、视觉语言模型（VLM）、嵌入模型和重排序模型。模型通过自动与手动控制相结合的方式进行管理：

• LRU逐出机制：当内存不足时，最近最少使用的模型会自动被逐出。
• 手动加载/卸载：管理员面板中的交互式状态标记允许您按需加载或卸载模型。
• 模型固定：将常用模型固定以始终保持加载状态。
• 每模型TTL：为每个模型设置空闲超时，在一段时间无活动后自动卸载。
• 进程内存限制：总内存上限（默认为系统RAM减去8GB）可防止系统范围内的内存溢出。

每模型设置

直接从管理员面板为每个模型配置采样参数、聊天模板关键字参数、TTL、模型别名、模型类型覆盖等。更改立即生效，无需重启服务器。

• 模型别名：设置一个自定义的API可见名称。/v1/models返回该别名，请求既可以接受别名，也可以接受目录名。
• 模型类型覆盖：无论自动检测结果如何，均可手动将模型设置为LLM或VLM。

内置聊天功能

可以直接从管理员面板与任何已加载的模型进行对话。支持对话历史、模型切换、暗模式、推理模型输出以及针对VLM/OCR模型的图像上传。

模型下载器

在管理员仪表盘中直接搜索并下载来自HuggingFace的MLX模型。浏览模型卡片，查看文件大小，并一键下载。

集成

只需单击一下按钮，即可在管理员仪表盘中直接设置OpenClaw、OpenCode和Codex，无需手动编辑配置。

性能基准测试

管理员面板中的一键基准测试。测量预填充（PP）和文本生成（TG）的每秒令牌数，并进行部分前缀缓存命中测试，以获得更贴近实际的性能数据。

macOS菜单栏应用

原生PyObjC菜单栏应用（非Electron）。无需打开终端即可启动、停止和监控服务器。包含持久化的服务统计信息（重启后仍保留）、崩溃后自动重启以及应用内自动更新。

API兼容性

可无缝替代OpenAI和Anthropic的API。支持流式使用统计（stream_options.include_usage）、Anthropic自适应思维以及视觉输入（base64、URL）。

工具调用与结构化输出

支持mlx-lm中所有可用的函数调用格式、JSON模式验证以及MCP工具集成。工具调用要求模型的聊天模板支持tools参数。以下模型家族可通过mlx-lm内置的工具解析器自动检测：

未列出以上的模型如果其聊天模板接受tools且输出采用公认的<|num_start|>XML格式，也可能正常工作。对于启用工具的流式响应，助手文本会逐步输出，同时隐藏已知的工具调用控制标记；完整的工具调用将在本轮对话结束后发出。

模型

将--model-dir指向包含MLX格式模型子目录的目录。也支持两层组织结构的文件夹（例如mlx-community/model-name/）。

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

模型会根据类型自动检测。您还可以直接从管理员仪表盘下载模型。

CLI配置

# 已加载模型的内存限制
omlx serve --model-dir ~/models --max-model-memory 32GB

# 进程级内存限制（默认：自动 = RAM - 8GB）
omlx serve --model-dir ~/models --max-process-memory 80%

# 启用KV块的SSD缓存
omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache

# 设置内存中的热缓存大小
omlx serve --model-dir ~/models --hot-cache-max-size 20%

# 调整最大并发请求数（默认：8）
omlx serve --model-dir ~/models --max-concurrent-requests 16

# 使用MCP工具
omlx serve --model-dir ~/models --mcp-config mcp.json

# HuggingFace镜像端点（适用于受限地区）
omlx serve --model-dir ~/models --hf-endpoint https://hf-mirror.com

# API密钥认证
omlx serve --model-dir ~/models --api-key your-secret-key
# 仅限本地访问：可通过管理员面板全局设置跳过验证

所有设置也可通过网页管理员面板在/admin处进行配置。设置会持久化到~/.omlx/settings.json，且CLI标志具有优先权。

FastAPI服务器（OpenAI / Anthropic API）
    │
    ├── 引擎池（多模型、LRU逐出、TTL、手动加载/卸载）
    │   ├── 批处理引擎（LLMs、连续批处理）
    │   ├── VLM引擎（视觉语言模型）
    │   ├── 嵌入引擎
    │   └── 重排序引擎
    │
    ├── 进程内存强制执行器（总内存限制、TTL检查）
    │
    ├── 调度器（先到先得、可配置并发度）
    │   └── mlx-lm批处理生成器
    │
    └── 缓存堆栈
        ├── 分页缓存管理器（GPU、基于块、写时复制、前缀共享）
        ├── 热缓存（内存层级、写回策略）
        └── 分页SSD缓存管理器（SSD冷层级、safetensors格式）

开发

命令行服务器

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

macOS 应用程序

需要 Python 3.11 或更高版本以及 venvstacks（运行 pip install venvstacks 安装）。

cd packaging

# 完整构建（包含 venvstacks、应用包和 DMG）
python build.py

# 跳过 venvstacks（仅代码更改）
python build.py --skip-venv

# 仅生成 DMG
python build.py --dmg-only

有关应用包结构和层配置的详细信息，请参阅 packaging/README.md。

参与贡献

欢迎各位参与贡献！详情请参阅 贡献指南。

• 错误修复和功能改进
• 性能优化
• 文档改进

许可证

Apache 2.0

致谢

• Apple 的 MLX 和 mlx-lm
• mlx-vlm —— 在 Apple Silicon 上进行视觉语言模型推理
• vllm-mlx —— oMLX 最初基于 vllm-mlx v0.1.0 开发，随后在多模型服务、分层 KV 缓存、支持完整分页缓存的 VLM、管理面板以及 macOS 菜单栏应用程序等方面得到了显著演进
• venvstacks —— 用于 macOS 应用包的便携式 Python 环境分层技术
• mlx-embeddings —— 对 Apple Silicon 的嵌入模型支持
• llm-compressor —— MoE 模型的 AWQ 参考实现，被用作 oQ 权重均衡设计的参考。

oMLX 快速上手指南

oMLX 是一款专为 Apple Silicon Mac 优化的本地大语言模型（LLM）推理工具。它支持连续批处理（Continuous Batching）和分层 KV 缓存（内存 + SSD），可通过菜单栏或命令行轻松管理，是运行本地 Coding Agent（如 Claude Code）的理想选择。

环境准备

在开始之前，请确保您的设备满足以下要求：

• 操作系统：macOS 15.0 (Sequoia) 或更高版本
• 硬件架构：Apple Silicon (M1 / M2 / M3 / M4 系列芯片)
• Python 版本：Python 3.10+
• 模型格式：需准备 MLX 格式的模型（可从 HuggingFace 下载或通过内置下载器获取）

安装步骤

您可以选择通过 Homebrew（推荐终端用户）或 macOS App（推荐图形界面用户）进行安装。

方式一：通过 Homebrew 安装（含 CLI 工具）

这是最灵活的安装方式，支持命令行服务和后台守护进程。

# 1. 添加 omlx 源
brew tap jundot/omlx https://github.com/jundot/omlx

# 2. 安装 omlx
brew install omlx

# 3. (可选) 启动为后台服务（崩溃自动重启）
brew services start omlx

# 4. (可选) 安装 MCP (Model Context Protocol) 支持
/opt/homebrew/opt/omlx/libexec/bin/pip install mcp

方式二：通过 macOS App 安装

适合偏好图形界面管理的用户。

1. 前往 Releases 页面 下载最新的 .dmg 文件。
2. 将 oMLX 拖入“应用程序”文件夹。
3. 启动应用，按照欢迎界面的指引设置模型目录并下载首个模型。
   • 注意：此方式不包含 omlx 命令行工具，如需终端调用请配合方式一使用。

方式三：从源码安装

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .          # 仅安装核心功能
# 或
pip install -e ".[mcp]"   # 包含 MCP 支持

基本使用

安装完成后，您可以通过命令行启动服务，或使用图形界面进行管理。

1. 启动推理服务

在终端中运行以下命令启动服务器（假设模型存放在 ~/models 目录）：

omlx serve --model-dir ~/models

• 服务启动后，会自动扫描子目录中的 LLM、VLM、Embedding 和 Reranker 模型。
• API 地址：http://localhost:8000/v1 (兼容 OpenAI 协议)
• 管理后台：http://localhost:8000/admin (内置 Web UI，支持模型下载、聊天测试、性能基准测试)

2. 作为后台服务运行 (Homebrew 用户)

如果您已通过 Homebrew 安装并希望开机自启或在后台运行：

# 启动服务
brew services start omlx

# 查看状态
brew services info omlx

# 停止服务
brew services stop omlx

默认配置下，服务会读取 ~/.omlx/models 目录并在 8000 端口运行。

3. 连接客户端

oMLX 完全兼容 OpenAI API，您可以直接在代码或支持 OpenAI 协议的客户端（如 Cursor, OpenClaw, OpenCode 等）中使用：

• Base URL: http://localhost:8000/v1
• API Key: 任意字符串 (例如 omlx)

Python 调用示例：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="omlx" 
)

response = client.chat.completions.create(
    model="Step-3.5-Flash-8bit", # 替换为您实际加载的模型目录名
    messages=[{"role": "user", "content": "Hello, oMLX!"}]
)

print(response.choices[0].message.content)

4. 核心特性提示

• 分层缓存：oMLX 会自动将频繁访问的 KV 块保留在内存（Hot Tier），不常用的卸载到 SSD（Cold Tier），即使重启服务器也能复用之前的上下文，极大节省显存。
• 模型管理：访问 http://localhost:8000/admin 可一键下载 HuggingFace 上的 MLX 模型、固定常用模型到内存或设置自动卸载时间。
• 多模型并发：支持同时加载文本、视觉 (VLM)、OCR 和 Embedding 模型，内存不足时会自动根据 LRU 策略卸载最少使用的模型。