oMLX简介oMLX是一款为Mac优化的大语言模型推理工具具备连续批处理和分层KV缓存功能可直接从菜单栏进行管理。联系邮箱junkim.dotgmail.com oMLX官网 。还有[安装] [快速开始] [特性] [模型] [CLI配置] [基准测试] [oMLX.ai]等相关内容以及[English] [中文] [한국어] [日本語]等语言选项。开发者表示尝试过的每个大语言模型LLM服务器都需在便利性和可控性之间做选择。希望将常用模型固定在内存中按需自动交换占用资源更多的模型设置上下文限制并从菜单栏管理。oMLX可在热内存层和冷SSD层之间持久化KV缓存即便对话中途上下文变化过往上下文也会被缓存可在不同请求中重复使用让本地大语言模型配合Claude Code等工具进行实际编码工作成为可能这也是开发它的原因。安装macOS应用程序从Releases下载.dmg文件拖移到“应用程序”文件夹完成安装。该应用支持内建自动更新未来升级一键操作。不过macOS应用程序不会安装omlx CLI命令若要在终端使用需通过Homebrew或从源代码安装。Homebrew安装# 安装 brew tap jundot/omlx https://github.com/jundot/omlx brew install omlx # 升级到最新版本 brew update brew upgrade omlx # 作为后台服务运行崩溃时自动重启 brew services start omlx # 可选MCP模型上下文协议支持 /opt/homebrew/opt/omlx/libexec/bin/pip install mcp从源代码安装git clone https://github.com/jundot/omlx.git cd omlx # 仅安装核心组件 pip install -e. # 安装带有MCP模型上下文协议支持的版本 pip install -e .[mcp]安装要求为macOS 15.0Sequoia、Python 3.10以及Apple SiliconM1/M2/M3/M4。快速开始macOS应用程序从“应用程序”文件夹启动oMLX欢迎界面会引导完成设置模型目录、启动服务器和下载第一个模型这三个步骤。若要连接OpenClaw、OpenCode或Codex可参考集成部分内容。CLI方式omlx serve --model-dir ~/models服务器会自动从子目录中发现大语言模型LLMs、视觉语言模型VLMs、嵌入模型和重排器。任何与OpenAI兼容的客户端都能连接到http://localhost:8000/v1内置聊天界面也可通过http://localhost:8000/admin/chat访问。Homebrew服务若通过Homebrew安装可将oMLX作为托管的后台服务运行# 启动崩溃时自动重启 brew services start omlx # 停止 brew services stop omlx # 重启 brew services restart omlx # 查看状态 brew services info omlx该服务以零配置默认值~/.omlx/models端口8000运行 omlx serve。若要自定义设置可设置环境变量如 OMLX_MODEL_DIR、OMLX_PORT 等或运行一次 omlx serve --model-dir /your/path将设置保存到 ~/.omlx/settings.json。日志记录在两个位置服务日志$(brew --prefix)/var/log/omlx.log标准输出/标准错误输出服务器日志~/.omlx/logs/server.log结构化应用程序日志。特性多模型支持支持在Apple Silicon上运行文本大语言模型LLMs、视觉语言模型VLMs、OCR模型、嵌入模型和重排器。管理仪表盘在 /admin 提供Web界面可进行实时监控、模型管理、聊天、基准测试以及针对每个模型进行设置。支持英语、韩语、日语、中文和俄语所有CDN依赖项都已打包可完全离线运行。视觉语言模型支持能像运行文本大语言模型一样通过连续批处理和分层KV缓存栈运行视觉语言模型。支持多图像聊天、Base64/URL/文件图像输入以及带有视觉上下文的工具调用。OCR模型如DeepSeek - OCR、DOTS - OCR、GLM - OCR会被自动检测并使用优化后的提示。分层KV缓存热 冷基于vLLM的块级KV缓存管理机制支持前缀共享和写时复制。缓存分为两层热层RAM频繁访问的块会保留在内存中实现快速访问冷层SSD热缓存满时块会以safetensors格式卸载到SSD。下次请求匹配到前缀时会从磁盘恢复这些块而非重新计算即使服务器重启也不受影响。连续批处理通过mlx - lm的BatchGenerator处理并发请求最大并发请求数可通过CLI或管理面板配置。Claude Code优化支持上下文扩展以便使用Claude Code运行小上下文模型。调整报告的令牌计数使自动压缩在合适时机触发并且SSE保持活动状态可防止长时间预填充期间的读取超时。多模型服务可在同一服务器上加载大语言模型、视觉语言模型、嵌入模型和重排器。模型通过自动和手动控制相结合的方式管理LRU驱逐内存不足时最近最少使用的模型会被自动驱逐手动加载/卸载管理面板中的交互式状态徽章可按需加载或卸载模型模型固定将常用模型固定使其始终保持加载状态每个模型的TTL为每个模型设置空闲超时时间一段时间不活动后自动卸载进程内存限制总内存限制默认系统内存 - 8GB可防止系统出现内存不足OOM的情况。每个模型的设置可直接从管理面板为每个模型配置采样参数、聊天模板参数、TTL、模型别名、模型类型覆盖等更改会立即生效无需重启服务器。模型别名设置自定义的API可见名称/v1/models 会返回别名请求时可使用别名或目录名称模型类型覆盖手动将模型设置为大语言模型或视觉语言模型不依赖自动检测。内置聊天功能可直接从管理面板与任何已加载的模型进行聊天支持对话历史记录、模型切换、暗黑模式、推理模型输出以及为视觉语言模型/OCR模型上传图像。模型下载器可在管理仪表盘中直接从HuggingFace搜索并下载MLX模型浏览模型卡片、查看文件大小一键即可完成下载。集成功能可直接从管理仪表盘一键设置OpenClaw、OpenCode、Codex和Pi无需手动编辑配置文件。性能基准测试可从管理面板一键进行基准测试测量每秒预填充PP和文本生成TG的令牌数并进行部分前缀缓存命中测试以获取更真实的性能数据。macOS菜单栏应用程序原生PyObjC菜单栏应用程序非Electron无需打开终端即可启动、停止和监控服务器包含持久化的服务统计信息重启后仍保留、崩溃自动重启以及内建自动更新功能。API兼容性可直接替代OpenAI和Anthropic的API支持流式使用统计信息stream_options.include_usage、Anthropic自适应思考以及视觉输入Base64、URL。端点说明POST /v1/chat/completions聊天完成流式POST /v1/completions文本完成流式POST /v1/messagesAnthropic消息APIPOST /v1/embeddings文本嵌入POST /v1/rerank文档重排GET /v1/models列出可用模型工具调用与结构化输出支持mlx - lm中所有可用的函数调用格式、JSON模式验证以及MCP工具集成。工具调用要求模型的聊天模板支持 tools 参数。以下模型系列可通过mlx - lm的内置工具解析器自动检测模型系列格式Llama、Qwen、DeepSeek等JSONQwen3.5系列XMLGemmaGLM (4.7, 5)XMLMiniMax命名空间Mistral[TOOL_CALLS]Kimi K2|tool_calls_section_begin|Longcat未列出的模型若其聊天模板支持工具且输出使用可识别的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/模型会自动检测类型也可直接从管理仪表盘下载模型。类型模型LLM任何mlx - lm支持的模型VLMQwen3.5系列、GLM - 4V、Pixtral以及其他mlx - vlm模型OCRDeepSeek - OCR、DOTS - OCR、GLM - OCR嵌入BERT、BGE - M3、ModernBERT重排器ModernBERT、XLM - RoBERTaCLI配置# 加载模型的内存限制 omlx serve --model-dir ~/models --max-model-memory 32GB # 进程级内存限制默认自动 系统内存 - 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% # 调整最大并发请求数默认8 omlx serve --model-dir ~/models --max-concurrent-requests 16 # 启用MCP工具 omlx serve --model-dir ~/models --mcp-config mcp.json # HuggingFace镜像端点适用于受限地区 omlx serve --model-dir ~/models --hf-endpoint https://hf-mirror.com # API密钥认证 omlx serve --model-dir ~/models --api-key your-secret-key # 仅本地访问通过管理面板全局设置跳过验证所有设置也可在 /admin 的Web管理面板中配置设置会保存到 ~/.omlx/settings.jsonCLI标志优先级更高。架构FastAPI Server (OpenAI / Anthropic API) │ ├── EnginePool (多模型、LRU驱逐、TTL、手动加载/卸载) │ ├── BatchedEngine (LLMs、连续批处理) │ ├── VLMEngine (视觉语言模型) │ ├── EmbeddingEngine │ └── RerankerEngine │ ├── ProcessMemoryEnforcer (总内存限制、TTL检查) │ ├── Scheduler (先来先服务、可配置并发) │ └── mlx-lm BatchGenerator │ └── Cache Stack ├── PagedCacheManager (GPU、块级、写时复制、前缀共享) ├── Hot Cache (内存层、回写) └── PagedSSDCacheManager (SSD冷层、safetensors格式)开发CLI服务器git clone https://github.com/jundot/omlx.git cd omlx pip install -e .[dev] pytest -m not slowmacOS应用程序需要Python 3.11和venvstackspip install venvstacks。cd packaging # 完整构建venvstacks 应用程序包 DMG python build.py # 跳过venvstacks仅代码更改 python build.py --skip-venv # 仅生成DMG python build.py --dmg-only有关应用程序包结构和层配置的详细信息可参阅 packaging/README.md。贡献欢迎贡献代码详细信息请参阅贡献指南包括修复bug、性能优化和文档改进等方面。许可证本项目采用Apache 2.0许可证。致谢MLX和mlx - lm由Apple开发mlx - vlm在Apple Silicon上进行视觉语言模型推理vllm - mlxoMLX从vllm - mlx v0.1.0起步并在多模型服务、分层KV缓存、支持全分页缓存的视觉语言模型、管理面板和macOS菜单栏应用程序等方面有显著发展venvstacks用于macOS应用程序包的便携式Python环境分层mlx - embeddings为Apple Silicon提供嵌入模型支持dflash - mlx在Apple Silicon上进行块扩散推测解码 。