README

oMLX
LLM 推理，为你的 Mac 优化连续批处理和分层 KV 缓存，直接从菜单栏管理。


  
  
  



  [email protected] · https://omlx.ai/me



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



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


---


  


 我试过的每个 LLM 服务器都让我在便利性和可控性之间做选择。我想把常用模型固定在内存中，按需自动切换较重的模型，设置上下文限制，并从菜单栏管理这一切。

 oMLX 将 KV 缓存持久化在热内存层和冷 SSD 层之间。即使对话中途上下文发生变化，所有历史上下文仍然保留在缓存中，可跨请求复用，让本地 LLM 在配合 Claude Code 等工具做实际编码时真正变得可用。这就是我做 oMLX 的原因。

 安装

 macOS 应用

从 Releases 下载 .dmg，拖到 Applications 即可。应用支持自动更新，后续升级只需一键完成。macOS 应用也会安装轻量的 ~/.omlx/bin/omlx CLI shim，因此可以从终端命令或 Apple Shortcuts 控制由应用管理的服务器。

 Homebrew

bash
brew tap jundot/omlx https://github.com/jundot/omlx
brew install omlx --with-custom-kernel    包含原生自定义内核（需要完整 Xcode）
 没有完整 Xcode 时，用 brew install omlx 安装不含内核的版本

 升级到最新版本
brew update && brew upgrade omlx

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

 可选：MCP（Model Context Protocol）支持，安装后重启以加载
/opt/homebrew/opt/omlx/libexec/bin/pip install mcp
omlx restart


 从源码安装

bash
git clone https://github.com/jundot/omlx.git
cd omlx
make install                 以 editable 模式安装（含 Web UI 和原生自定义内核）
 没有完整 Xcode 时，用 make install-no-kernels 安装不含内核的版本
make mcp                     可选：添加 MCP 支持，重启 omlx serve 后加载


需要 macOS 15.0+ (Sequoia)、Python 3.11–3.13 和 Apple Silicon（M1/M2/M3/M4/M5）。

 关于原生自定义内核： GLM-5.2、MiniMax M3 和 Qwen3.5 需要这些内核，缺少时会在没有提示的情况下回退到慢得多的通用路径。make install 会一并构建内核并检查每个内核都能加载，这需要带 Metal 工具链的完整 Xcode（xcodebuild -downloadComponent MetalToolchain），仅有 Command Line Tools 不够。没有 Xcode 时，请使用已预编译内核的官方 DMG，或使用 make install-no-kernels。make kernels 只从头重新构建内核。检查安装：

 bash
 python -c "from omlx.custom_kernels import native_kernel_status; print(native_kernel_status())"
 

 快速开始

 macOS 应用

从 Applications 文件夹启动 oMLX。欢迎界面会引导你完成三个步骤 — 模型目录设置、服务器启动、首个模型下载。就是这样。要连接 OpenClaw、OpenCode、Codex、Hermes Agent、Copilot 或 DeepSeek Harness，请参阅集成。


  
  


 CLI

bash
omlx serve --model-dir ~/models


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

 Homebrew 服务

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

bash
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（结构化应用日志）

 功能

在 Apple Silicon 上支持文本 LLM、视觉语言模型（VLM）、OCR 模型、嵌入模型和重排序模型。

 管理后台

在 /admin 提供实时监控、模型管理、聊天、基准测试和模型级设置的 Web UI。支持英语、韩语、日语、中文和俄语。所有 CDN 依赖已内置，完全支持离线运行。


  


 实验性多 Mac 推理

源码构建版本可通过基于 Ring 或雷雳（Thunderbolt）RDMA/JACCL 的 MLX 流水线秩，将已下载的单一语言模型拆分并运行在多台内存规格不等的 Mac 上。集群仪表盘支持只读节点发现、严格的 SSH/运行时校验、感知字节级差异的分片规划、实测算力与链路负载均衡、感知内存余量的执行调优、激活，并在两台 Mac 上提供实时的分片与性能图谱。交互模式、均衡模式与吞吐量配置模式公开了合并批处理、提示词缓存亲和性、轮换 KV 限制、Ring 连接调优以及受能力门禁控制的实验性纯 Token 输出路径。有关安装设置、安全边界、当前限制以及物理硬件验证清单，请参阅跨 Mac 分布式推理。

 视觉语言模型

使用与文本 LLM 相同的连续批处理和分层 KV 缓存堆栈运行 VLM。支持