首页 / 开源热榜 / oMLX / 使用教程

oMLX 中文教程：Mac 安装、模型服务与缓存设置

更新于 2026-09-23 · NGJOO AI 实验室 · 约 10 分钟

oMLX 是面向 Apple Silicon Mac 的本地模型服务器。它在 MLX 推理上加入连续批处理、RAM 与 SSD 两级 KV 缓存、多模型内存管理、Web 管理端，以及 OpenAI 和 Anthropic 兼容接口。

版本要分清：当前稳定版是 v0.6.4，发布于 2026-08-29；v0.7.0.dev4 发布于 2026-09-18，但它是预发布版。本文的安装基线采用稳定版。

1. 安装前先检查环境

Apple Silicon：M1、M2、M3、M4 或 M5。
macOS 15.0 以上。
源码安装要求 Python 3.11 至 3.13；以 pyproject.toml 的 >=3.11,<3.14 为准。
准备足够的统一内存和磁盘空间。模型文件与 SSD KV 缓存都会占空间。

README 的项目分类器仍出现 Python 3.10，但实际安装约束已经排除 3.10，因此不能照旧教程使用 Python 3.10。

2. 选择一种安装方式

希望少折腾可以从 v0.6.4 Release 下载 DMG。终端用户可以使用官方 Homebrew tap：

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

# 查看服务命令
omlx --help

需要查看源码或参与开发时再用可编辑安装：

git clone https://github.com/jundot/omlx.git
cd omlx
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

原生内核边界：官方说明部分模型族使用普通源码安装时会退回较慢路径。构建原生自定义内核需要完整 Xcode，只有 Command Line Tools 不够。先确认模型确实需要该路径，再按官方说明安装。

3. 第一次启动只监听本机

先建一个单独的模型目录，把 MLX 格式模型放在其子目录中，再以前台方式启动：

mkdir -p ~/models
omlx serve --model-dir ~/models

# 另开一个终端检查模型发现
curl http://localhost:8000/v1/models

管理端地址是 http://localhost:8000/admin，聊天页是 /admin/chat。先确认模型名称、内存变化和一次短对话，再接入 Codex、OpenCode 等客户端。这样出错时更容易判断是模型、服务还是客户端配置。

4. 再决定是否开启 SSD KV 缓存

omlx serve --model-dir ~/models \
  --paged-ssd-cache-dir ~/.omlx/cache \
  --paged-ssd-cache-max-size 20GB

这类缓存复用的是匹配的请求前缀。它不会让所有请求都更快，也不能替代模型推理。先固定模型和提示词做有缓存、无缓存两组测试，同时观察首 token 时间、磁盘占用和内存；不要照搬官方或他人的单机速度数字。

5. 局域网访问必须先加鉴权

OMLX_API_KEY='换成足够长的随机值' \
omlx serve --model-dir ~/models --host 0.0.0.0

官方实现会在非 loopback 地址没有 API key 时拒绝启动。即使已有 key，也要用系统防火墙限制来源，不要直接暴露到公网。模型接口能看到或处理提示词、文件内容与工具调用，权限范围应当按生产数据来管理。

6. oMLX 与 MLX LM server 怎么选

维度	oMLX	MLX LM server
定位	长期管理多个模型的本地服务	MLX LM 自带的基础 HTTP 服务
管理能力	管理面板、菜单栏、LRU、TTL、模型固定驻留	命令行启动单个模型更直接
缓存	RAM 热层与 SSD 冷层、前缀共享	提供 prompt cache 与批处理基础能力
安全提示	非本机监听强制 API key	官方文档写明只实现基本安全检查，不建议直接用于生产

oMLX 的连续批处理本身使用 mlx-lm BatchGenerator。只想快速启动一个模型时，MLX LM server 更简单；需要多模型、SSD 缓存和图形化运维时，oMLX 的封装更省事。

7. 本次验证边界

验证状态：本次核对了官方 README、pyproject.toml、Apache-2.0 LICENSE、GitHub Releases 和仓库元数据；没有在 Apple Silicon Mac 上安装或运行。

已经确认：稳定版与预发布版的区别、系统和 Python 要求、官方安装命令、默认端口、接口类型、缓存结构与远程鉴权规则均有官方材料对应。

没有验证：模型加载、实际吞吐、SSD 缓存命中、内存回收、自定义内核、API 完整兼容性和多 Mac 集群。文中的操作步骤是文档核对结果，不是本站实测成绩。

这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。

先判断这个项目是否适合你

适合谁用

适合用 Apple Silicon Mac 搭建本地编码助手后端、离线聊天、视觉/OCR、embedding 或 reranker 服务，并希望在一个管理面板中控制多个模型和内存占用的用户。

采用建议

如果你有 Apple Silicon Mac，并且要长期运行多个本地模型、复用长对话前缀、统一接入编码工具，oMLX 值得先在 localhost 小范围验证。生产或局域网使用前，应逐项测试模型兼容、缓存占用和鉴权；只需一个简单模型服务时可先考虑更小的 MLX LM server。

原教程未展开的系统信息

核心功能

多模型管理
同一服务可以发现 LLM、VLM、OCR、embedding 和 reranker 模型，并用 LRU、固定驻留和每模型 TTL 控制内存。
macOS 菜单栏和命令行
官方 DMG 包含原生 Swift/SwiftUI 菜单栏应用和 CLI shim；Homebrew 或源码安装也能用 omlx start、stop、restart 与 serve 管理服务。

架构与数据流

FastAPI 层提供 OpenAI/Anthropic API；EnginePool 管理文本、视觉、向量和重排引擎；调度器使用 mlx-lm BatchGenerator；PagedCacheManager、RAM 热缓存和 SSD 冷缓存组成缓存栈；ProcessMemoryEnforcer 负责总内存与 TTL。

技术栈和运行条件

语言

Python；macOS 应用使用 Swift/SwiftUI

框架

MLX、mlx-lm、FastAPI

关键依赖

Python >=3.11,<3.14
macOS 15.0+
Apple Silicon M1-M5

运行环境

本机服务默认监听 localhost:8000；模型与设置默认放在 ~/.omlx；可选 SSD KV 缓存

常见问题

oMLX 能在 Intel Mac、Windows 或 Linux 上运行吗？

不能按官方支持路径运行。当前要求 Apple Silicon、macOS 15.0 以上和 Python 3.11 至 3.13。

应该安装 oMLX 0.6.4 还是 0.7.0.dev4？

需要稳定环境时选 0.6.4。0.7.0.dev4 被 GitHub 标为预发布，发布说明也建议遇到回归时退回较早开发版。

把 oMLX 开放到局域网需要做什么？

先配置 API key，再修改监听地址。官方说明服务在非 loopback 地址且没有 API key 时会拒绝启动。

oMLX 的 SSD 缓存会让所有请求都更快吗？

不会。它只在请求前缀能够匹配时复用缓存；磁盘速度、缓存上限、模型和上下文变化都会影响收益。本站没有实测具体加速比例。