## 项目概述

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](https://github.com/jundot/omlx/releases) 下载 .dmg 文件，拖入 Applications 文件夹即可。应用包含自动更新功能。

### Homebrew

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

### 从源码安装

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

**快速开始：**

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

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

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

## 典型使用方法

### 使用 OpenAI 客户端

```python
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 客户端

```python
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)
```

### 命令行管理

```bash
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 的日期）。