跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
PythonAI算法

oMLX：Mac 本地大语言模型推理框架

oMLX 是专为 Apple Silicon Mac 优化的本地大语言模型推理框架，支持文本 LLM、视觉语言模型及 OCR 等。核心特性包括分层 KV 缓存（热缓存 RAM+ 冷缓存 SSD）、连续批处理调度及多模型协同服务。提供 macOS 原生应用、CLI 工具及管理后台 Web UI，兼容 OpenAI 和 Anthropic API。支持模型下载、基准测试及工具调用，适用于本地开发辅助、企业私有化部署及资源受限环境优化。

协议工匠发布于 2026/3/30更新于 2026/5/2333 浏览
oMLX：Mac 本地大语言模型推理框架

一、项目定位

oMLX 是一个专为 Apple Silicon Mac 优化的本地大语言模型推理框架，核心目标是在便利性与可控性之间取得平衡，让本地 LLM 在实际编码、多轮对话等场景中真正可用。

  • GitHub: https://github.com/jundot/omlx
  • 中文说明：https://github.com/jundot/omlx/blob/main/README.zh.md
  • 官网：https://omlx.ai/

二、安装

方式一：下载 macOS 应用

下载 DMG 拖入 Applications，支持自动更新。下载地址：https://github.com/jundot/omlx/releases

方式二：Homebrew
brew tap jundot/omlx https://github.com/jundot/omlx
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
方式三：从源码安装

需 Python 3.10+ 与 Apple Silicon。

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .
# 仅核心
pip install -e ".[mcp]"
# 含 MCP（Model Context Protocol）支持

三、快速开始

1、macOS 应用

从 Applications 文件夹启动 oMLX。欢迎界面会引导你完成三个步骤 — 模型目录设置、服务器启动、首个模型下载。

oMLX 欢迎界面

oMLX 菜单栏

2、CLI
omlx serve --model-dir ~/models

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

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

四、功能

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

1、管理后台

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

oMLX 管理后台

2、视觉语言模型

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

3、分层 KV 缓存（热缓存 + 冷缓存）

借鉴 vLLM 的基于块的 KV 缓存管理，支持前缀共享和写时复制（Copy-on-Write）。缓存分为两个层级：

  • 热缓存（RAM）: 频繁访问的块保留在内存中，实现快速读取。
  • 冷缓存（SSD）: 热缓存满时，块会以 safetensors 格式转存到 SSD。下次请求命中相同前缀时，直接从磁盘恢复，无需重新计算 — 即使服务器重启也不会丢失。

oMLX 热缓存与冷缓存

4、连续批处理

通过 mlx-lm 的 BatchGenerator 处理并发请求。预填充和补全批大小可配置。

5、Claude Code 优化

支持在 Claude Code 中使用较小上下文模型的上下文缩放。通过缩放上报的 Token 数量，让自动压缩在合适的时机触发，同时提供 SSE keep-alive 防止长时间预填充导致的读取超时。

6、多模型服务

在同一服务器中加载 LLM、VLM、嵌入模型和重排序模型。通过自动和手动控制的组合管理模型：

  • LRU 驱逐: 内存不足时，最近最少使用的模型会被自动卸载。
  • 手动加载/卸载: 在管理后台通过状态标识按需加载或卸载模型。
  • 模型固定: 固定常用模型使其始终保持加载状态。
  • 模型级 TTL: 为每个模型设置空闲超时，在一段时间不活动后自动卸载。
  • 进程内存限制: 总内存限制（默认：系统 RAM - 8GB）防止系统级 OOM。
7、模型级设置

在管理后台直接配置每个模型的采样参数、聊天模板参数、TTL、模型别名、模型类型覆盖等。修改即时生效，无需重启服务器。

  • 模型别名: 设置自定义 API 显示名称。/v1/models 返回别名，请求时别名和目录名均可使用。
  • 模型类型覆盖: 无论自动检测结果如何，手动设置为 LLM 或 VLM。

oMLX 聊天模板参数

8、内置聊天

从管理后台直接与已加载的模型聊天。支持对话历史、模型切换、深色模式、推理模型输出，以及 VLM/OCR 模型的图片上传。

oMLX 聊天

9、模型下载器

在管理后台中直接搜索和下载 HuggingFace 上的 MLX 模型。浏览模型卡片、查看文件大小，一键下载。

oMLX 模型下载器

10、性能基准测试

从管理后台一键运行基准测试。测量预填充（PP）和 Token 生成（TG）的每秒 Token 数，包含部分前缀缓存命中测试以获得真实的性能数据。

oMLX 基准测试工具

11、macOS 菜单栏应用

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

oMLX 菜单栏统计

12、API 兼容性

OpenAI 和 Anthropic API 的直接替代品。支持流式使用统计（stream_options.include_usage）、Anthropic adaptive thinking 和视觉输入（base64、URL）。

端点说明
POST /v1/chat/completions聊天补全（流式）
POST /v1/completions文本补全（流式）
POST /v1/messagesAnthropic Messages API
POST /v1/embeddings文本嵌入
POST /v1/rerank文档重排序
GET /v1/models列出可用模型
13、工具调用与结构化输出

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

模型系列格式
Llama、Qwen、DeepSeek 等JSON <tool_call>
Qwen3.5 系列XML <function=...>
Gemma<start_function_call>
GLM (4.7, 5)<arg_key>/<arg_value> XML
MiniMaxNamespaced <minimax:tool_call>
Mistral[TOOL_CALLS]
Kimi K2<
Longcat<longcat_tool_call>

上表未列出的模型，只要聊天模板支持 tools 参数且输出采用可识别的 <tool_call> 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/

模型会按类型自动识别。也可以直接在管理后台下载模型。

类型模型
LLMmlx-lm 支持的所有模型
VLMQwen3.5 系列、GLM-4V、Pixtral 及其他 mlx-vlm 模型
OCRDeepSeek-OCR、DOTS-OCR、GLM-OCR
嵌入BERT、BGE-M3、ModernBERT
重排序ModernBERT、XLM-RoBERTa

六、CLI 配置

# 已加载模型的内存限制
omlx serve --model-dir ~/models --max-model-memory 32GB
# 进程级内存限制（默认：auto = 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%
# 调整批大小
omlx serve --model-dir ~/models --prefill-batch-size 8 --completion-batch-size 32
# 使用 MCP 工具
omlx serve --model-dir ~/models --mcp-config mcp.json
# API 密钥认证
omlx serve --model-dir ~/models --api-key your-secret-key
# 仅限 Localhost：在管理后台全局设置中跳过验证

以上所有设置也可以在 /admin 的 Web 管理后台中配置。设置保存在 ~/.omlx/settings.json，CLI 参数优先级更高。

七、架构

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 (内存缓存，write-back)
    └── PagedSSDCacheManager (SSD 冷缓存，safetensors 格式)

八、开发

1、CLI 服务器
git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e ".[dev]"
pytest -m "not slow"
2、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。

九、分析

1、核心技术特点
1、分层 KV 缓存架构
  • 热缓存（RAM）：高频访问的 KV 块保留在内存，实现毫秒级读取
  • 冷缓存（SSD）：内存满时自动将块以 safetensors 格式持久化到磁盘，支持跨请求、跨重启复用
  • 前缀共享 + 写时复制：借鉴 vLLM 的块管理机制，减少重复计算，提升长上下文效率
2、连续批处理调度
  • 基于 mlx-lm 的 BatchGenerator 实现并发请求合并
  • 预填充与生成阶段批大小可独立配置，平衡延迟与吞吐
3、多模型协同服务
  • 同一进程内支持 LLM、VLM、OCR、嵌入、重排序模型混合部署
  • 支持 LRU 自动驱逐、手动加载/卸载、模型固定、TTL 空闲超时、进程级内存保护等多级资源策略
2、关键功能模块
1）可视化管理后台
  • 提供 /admin Web UI，支持实时监控、模型管理、聊天测试、基准测试
  • 支持中英日韩四语言，CDN 资源本地化，可完全离线运行
2）菜单栏原生应用
  • 基于 PyObjC 开发的 macOS 原生菜单应用（非 Electron）
  • 支持一键启停服务、持久化统计、崩溃自动重启、应用内更新
3）视觉与 OCR 能力
  • VLM 与文本模型共享同一缓存与批处理栈，支持多图输入、base64/URL/文件上传
  • 自动识别 DeepSeek-OCR、DOTS-OCR 等模型，优化提示词适配
4）开发者友好配置
  • OpenAI / Anthropic API 完全兼容，支持流式统计、adaptive thinking、视觉输入
  • 支持函数调用、JSON Schema 验证、MCP 工具集成，覆盖主流模型格式
  • 模型级参数（采样、模板、TTL、别名）支持热更新，无需重启服务
5）内置工具链
  • 模型下载器：管理后台直接搜索并下载 HuggingFace 上的 MLX 格式模型
  • 基准测试：一键测量预填充/生成吞吐，支持前缀缓存命中率评估
  • 内置聊天：支持对话历史、模型切换、深色模式、图片上传
3、适用场景与价值
1）本地开发辅助
  • 配合 Claude Code 等工具，通过上下文缩放与缓存复用，让小模型处理长对话编码任务
2）企业私有化部署
  • 离线可用、数据不出本地，适合对隐私敏感的研发、财务、法务场景
3）多模态任务处理
  • 统一框架支持文本、图像、文档解析，简化技术栈维护成本
4）资源受限环境优化
  • 分层缓存 + 内存保护机制，让 16GB/32GB 内存的 Mac 也能稳定运行 70B+ 参数模型
4、技术栈与生态
  • 底层框架：Apple MLX + mlx-lm + mlx-vlm
  • 服务层：FastAPI + PyObjC 原生菜单应用
  • 缓存层：自定义 PagedCacheManager + SSD 持久化
  • 兼容生态：OpenAI API、Anthropic Messages API、MCP 协议、HuggingFace 模型库
5、致谢
  • MLX 和 mlx-lm by Apple
  • mlx-vlm - Apple Silicon 上的视觉语言模型推理
  • vllm-mlx - oMLX 从 vllm-mlx v0.1.0 起步，经过大幅演进，增加了多模型服务、分层 KV 缓存、完整分页缓存支持的 VLM、管理后台和 macOS 菜单栏应用
  • venvstacks - macOS 应用包的便携 Python 环境分层
  • mlx-embeddings - Apple Silicon 嵌入模型支持

目录

  1. 一、项目定位
  2. 二、安装
  3. 方式一：下载 macOS 应用
  4. 方式二：Homebrew
  5. 升级到最新版本
  6. 作为后台服务运行（崩溃时自动重启）
  7. 可选：MCP（Model Context Protocol）支持
  8. 方式三：从源码安装
  9. 仅核心
  10. 含 MCP（Model Context Protocol）支持
  11. 三、快速开始
  12. 1、macOS 应用
  13. 2、CLI
  14. 3、Homebrew 服务
  15. 四、功能
  16. 1、管理后台
  17. 2、视觉语言模型
  18. 3、分层 KV 缓存（热缓存 + 冷缓存）
  19. 4、连续批处理
  20. 5、Claude Code 优化
  21. 6、多模型服务
  22. 7、模型级设置
  23. 8、内置聊天
  24. 9、模型下载器
  25. 10、性能基准测试
  26. 11、macOS 菜单栏应用
  27. 12、API 兼容性
  28. 13、工具调用与结构化输出
  29. 五、模型
  30. 六、CLI 配置
  31. 已加载模型的内存限制
  32. 进程级内存限制（默认：auto = RAM - 8GB）
  33. 启用 KV 块的 SSD 缓存
  34. 设置内存热缓存大小
  35. 调整批大小
  36. 使用 MCP 工具
  37. API 密钥认证
  38. 仅限 Localhost：在管理后台全局设置中跳过验证
  39. 七、架构
  40. 八、开发
  41. 1、CLI 服务器
  42. 2、macOS 应用
  43. 完整构建（venvstacks + 应用包 + DMG）
  44. 跳过 venvstacks（仅代码更改）
  45. 仅 DMG
  46. 九、分析
  47. 1、核心技术特点
  48. 1、分层 KV 缓存架构
  49. 2、连续批处理调度
  50. 3、多模型协同服务
  51. 2、关键功能模块
  52. 1）可视化管理后台
  53. 2）菜单栏原生应用
  54. 3）视觉与 OCR 能力
  55. 4）开发者友好配置
  56. 5）内置工具链
  57. 3、适用场景与价值
  58. 1）本地开发辅助
  59. 2）企业私有化部署
  60. 3）多模态任务处理
  61. 4）资源受限环境优化
  62. 4、技术栈与生态
  63. 5、致谢
  • 💰 8折买阿里云服务器限时8折了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

更多推荐文章

查看全部
  • 人工智能核心概念速通教程
  • AI 产品经理产品开发全流程详解：从需求定义到模型验收
  • 贪心算法（Greedy Algorithm）核心原理与实现
  • VRM4U 插件在 Unreal Engine 5 中的使用指南
  • 锐龙 AI 7 H 350 与锐龙 7 H 255 对比评测
  • 2026 年高校 AIGC 检测新规解读：AI 率合格标准分析
  • opencode 集成 Git：AI 辅助版本控制操作指南
  • Qwen3.5-4B 微调实战：基于 LLaMA-Factory 构建医疗 AI 助手
  • NFT 元数据去中心化存储与智能合约集成实战
  • AI 数据标注平台选型实践：效率提升背后的技术逻辑
  • Ubuntu 22.04 下基于 ROS2 Humble 的 PX4 无人机仿真环境搭建
  • 大模型推理服务框架 Ollama 一键部署指南
  • DFT 中的片上时钟控制器（OCC）架构设计与插入规则
  • 基于 ESP32 的无人机飞控 LOG 记录：SD NAND 存储方案测试
  • 从零开始构建简单 RAG 应用指南
  • Vue Print Designer 前端可视化打印设计器详解
  • 性能测试、敏捷开发与全排列算法实战
  • OpenClaw QQ 机器人接入指南
  • Java Web 开发入门指南：基础、环境与核心技术
  • Microsoft GSL 实战：解决 C++ 内存安全问题的方法

相关免费在线工具

  • 加密/解密文本

    使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Gemini 图片去水印

    基于开源反向 Alpha 混合算法去除 Gemini/Nano Banana 图片水印，支持批量处理与下载。 在线工具，Gemini 图片去水印在线工具，online

  • curl 转代码

    解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online