GitShelf — GitHub 项目目录

项目概述

oMLX 是一个专为 Apple Silicon Mac 优化的 LLM 推理服务器，支持连续批处理（continuous batching）和分层 KV 缓存（tiered KV cache），并可通过 macOS 菜单栏应用进行管理。它提供 OpenAI 和 Anthropic 兼容的 API，支持文本 LLM、视觉语言模型（VLM）、OCR、嵌入和重排序模型。项目采用 Apache-2.0 许可证，主要使用 Python 和 Swift 开发。

核心功能

连续批处理：通过 mlx-lm 的 BatchGenerator 处理并发请求，可配置最大并发数。
分层 KV 缓存：热层（RAM）和冷层（SSD）两级缓存，支持前缀共享和写时复制（CoW），即使上下文变化或服务器重启，历史缓存仍可复用。
多模型服务：同一服务器可加载 LLM、VLM、嵌入和重排序模型，支持 LRU 驱逐、手动加载/卸载、模型固定和每模型 TTL。
管理仪表盘：Web UI（/admin）提供实时监控、模型管理、聊天、基准测试和每模型设置，支持多语言，完全离线运行。
macOS 菜单栏应用：原生 SwiftUI 应用，无需终端即可启动、停止和监控服务器，支持自动重启和自动更新。
API 兼容性：作为 OpenAI 和 Anthropic API 的即插即用替代品，支持流式、工具调用、结构化输出和视觉输入。
模型下载器：直接从仪表盘搜索和下载 HuggingFace 上的 MLX 模型。
集成：一键配置 OpenClaw、OpenCode、Codex、Hermes Agent、Copilot 等工具。
性能基准：一键测量预填充和生成速度，支持部分前缀缓存命中测试。
实验性 DFlash 支持：集成块扩散推测解码，加速特定模型（如 Qwen、Gemma4、Laguna）的生成。

适用与不适用场景

适用场景：

在 Apple Silicon Mac（M1/M2/M3/M4）上本地运行 LLM 推理服务。
需要同时服务多种模型类型（LLM、VLM、嵌入、重排序）的场景。
需要长上下文缓存以加速重复对话或工具调用（如 Claude Code）的场景。
希望使用菜单栏应用便捷管理推理服务器的 macOS 用户。
需要 OpenAI 或 Anthropic 兼容 API 的本地开发或测试环境。

不适用场景：

非 Apple Silicon 平台（如 Intel Mac、Linux、Windows）。
需要 GPU 加速的 NVIDIA 或其他非 Apple 硬件。
需要大规模生产级部署（如多节点集群）。
对推理速度有极致要求且不介意使用非本地服务的场景。

技术架构与依赖

核心语言：Python 3.11–3.13，macOS 应用使用 Swift/SwiftUI。
推理引擎：基于 MLX 和 mlx-lm，VLM 支持基于 mlx-vlm。
服务器框架：FastAPI。
缓存机制：分页 KV 缓存（受 vLLM 启发），热层（RAM）和冷层（SSD，safetensors 格式）。
调度器：FCFS 调度，可配置并发。
内存管理：进程内存强制器，防止系统级 OOM。
可选依赖：MCP（Model Context Protocol）支持，DFlash 推测解码（dflash-mlx）。
量化工具：oQ 通用动态量化系统，支持混合精度量化。

安装与快速开始

macOS 应用

从 Releases 下载 .dmg 文件，拖入 Applications 文件夹即可。应用包含自动更新功能。

Homebrew

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

从源码安装

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .          # 核心安装
pip install -e ".[mcp]"   # 带 MCP 支持

快速开始：

# 启动服务器（后台服务）
omlx start

# 或前台运行
omlx serve --model-dir ~/models

服务器自动发现模型目录中的模型，默认端口 8000，OpenAI 兼容客户端可连接 http://localhost:8000/v1。

典型使用方法

使用 OpenAI 客户端

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="your-key")
response = client.chat.completions.create(
    model="Qwen3-Coder-Next-8bit",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

使用 Anthropic 客户端

from anthropic import Anthropic

client = Anthropic(base_url="http://localhost:8000/v1", api_key="your-key")
message = client.messages.create(
    model="Qwen3-Coder-Next-8bit",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
print(message.content[0].text)

命令行管理

omlx start
omlx stop
omlx restart
omlx serve --model-dir ~/models --memory-guard safe --paged-ssd-cache-dir ~/.omlx/cache

配置与部署要点

模型目录：通过 --model-dir 指定，支持子目录自动发现。
内存保护：--memory-guard 和 --memory-guard-gb 控制内存上限。
缓存配置：--paged-ssd-cache-dir 启用 SSD 缓存，--hot-cache-max-size 设置热缓存大小。
并发控制：--max-concurrent-requests 调整最大并发请求数。
API 密钥：--api-key 设置认证密钥。
HuggingFace 镜像：--hf-endpoint 用于受限区域。
设置持久化：所有设置保存到 ~/.omlx/settings.json，CLI 参数优先。
自定义内核：GLM-5.2 / MiniMax M3 等模型需要编译自定义内核，需完整 Xcode。

限制、风险与许可证

平台限制：仅支持 Apple Silicon 和 macOS 15.0+。
模型支持：DFlash 仅支持特定模型家族（Qwen、Gemma4、Laguna），其他模型需自行验证。
性能风险：未编译自定义内核时，某些模型会回退到慢速路径，性能大幅下降。
实验性功能：DFlash 和 oQ 量化属于实验性，可能不稳定。
许可证：Apache-2.0。

官方链接

GitHub 仓库：https://github.com/jundot/omlx
发布页面：https://github.com/jundot/omlx/releases
官方网站：https://omlx.ai
基准测试：https://omlx.ai/benchmarks
联系邮箱：junkim.dot@gmail.com

信息来源和分析时间

信息来源：GitHub 仓库 README、文档（CONTRIBUTING.md、dflash_mlx_integration.md、oQ_Quantization.md）、最新发布信息。
分析时间：2026-08-04（基于最新发布 v0.5.7 的日期）。

项目概览