oMLX 快速上手教程：5 分钟在 Mac 上跑起第一个本地大模型

oMLX 快速上手教程：5 分钟在 Mac 上跑起第一个本地大模型

【免费下载链接】omlxLLM inference server with continuous batching & SSD caching for Apple Silicon — managed from the macOS menu bar项目地址: https://gitcode.com/GitHub_Trending/om/omlx

oMLX 是一款免费开源的 LLM 推理服务器，专为 Apple Silicon（M 系列芯片）优化：它支持连续批处理、SSD 冷热分层 KV 缓存，还可以直接在 macOS 菜单栏管理。跟着这篇本地大模型部署教程，5 分钟就能让大模型在 Mac 上离线跑起来。

环境要求与安装 oMLX 的两种方式

运行 oMLX 本地大模型服务只需满足三个条件：

• Apple Silicon 芯片（M1 / M2 / M3 / M4 / M5）
• macOS 15.0（Sequoia）及以上
• Python 3.11 – 3.13（安装官方 macOS 应用时无需手动配置）

方式一：下载 macOS 菜单栏应用（推荐新手）

从 Releases 页面下载.dmg，拖入「应用程序」文件夹即完成安装。应用自带一键自动更新，并会安装轻量 CLI 垫片~/.omlx/bin/omlx，方便终端控制服务。首次启动会弹出欢迎向导，按三步走即可：

oMLX 快速上手教程：欢迎向导三步配置模型目录、端口并启动本地大模型服务器

1. Step 1 初始配置：确认 Base Directory、Model Directory（默认~/.omlx/models）与端口（默认 8000）
2. Step 2 Start Server：点击按钮启动本地推理服务
3. Step 3 Open Settings：打开管理面板，准备下载模型

方式二：Homebrew 一键安装

如果你习惯命令行，两条命令装好 oMLX 推理服务器：

brew tap jundot/omlx https://gitcode.com/GitHub_Trending/om/omlx brew install jundot/omlx/omlx

随后用生命周期命令管理后台服务（崩溃自动重启）：

omlx start # 启动后台服务 omlx stop # 停止 omlx restart # 重启

日志分别在~/.omlx/logs/server.log（结构化应用日志）和$(brew --prefix)/var/log/omlx.log（服务日志）。

💡 临时体验？也可以用前台模式直接跑：omlx serve --model-dir ~/models，服务会默认监听 8000 端口，模型目录自动发现。

用内置下载器获取你的第一个模型

打开浏览器访问管理面板http://localhost:8000/admin，切换到Downloader选项卡，即可在面板内直接搜索并下载 Hugging Face 上的 MLX 格式模型：

选择建议：

• M1 / M2：优先选 4bit 量化、参数 7B 左右的模型
• M3 / M4 / M5 及以上：可挑战 30B 级别的中型模型
• 注意磁盘空间：面板会显示每个模型的文件大小

下载完成后模型自动落入模型目录，服务器会按类型自动识别（LLM / VLM / OCR / Embedding / Reranker），无需任何手动配置。

打开内置 Chat 界面，与大模型对话

进入面板的Chat选项卡，选择已加载的模型，即可直接对话：

内置 Chat 支持会话历史、模型切换、暗色模式、推理模型输出展示，视觉模型（VLM）还能直接上传图片提问。到这里，你的第一个本地大模型就跑起来了 🎉

想测速？面板里的一键 Benchmark 会分别测出PP（Prefill）与TG（Token Generation）每秒 token 数，并包含前缀缓存命中的真实场景数据。

管理面板与 API：像用 OpenAI 一样用 oMLX

Status 主面板实时展示服务状态与统计数据：

面板顶部还直接给出可用的 API 端点：

• OpenAI 兼容 API：http://localhost:8000/v1
• Anthropic 兼容 API：http://localhost:8000

任何 OpenAI 兼容客户端都能直接接入，例如：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "your-model", "messages": [{"role": "user", "content": "你好"}], "stream": true}'

菜单栏 App 让管理更轻量：不打开终端即可启停服务、查看持久化服务统计，崩溃自动拉起。

进阶能力速览

常见问题（FAQ）

• 内存不够 / 想限制内存上限？启动时加--memory-guard safe或--memory-guard-gb 48设置内存护栏，默认上限为「系统内存 − 8GB」，避免整机 OOM。
• 端口被占用？在欢迎向导或管理面板中修改端口，或用omlx serve --model-dir ~/models配合环境变量OMLX_PORT。
• 想启用 SSD 缓存？omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache，KV 块将以 safetensors 格式落盘，前缀命中时从磁盘恢复而非重算。
• 国产镜像加速？可加--hf-endpoint https://hf-mirror.com指定 Hugging Face 镜像端点。

项目关键路径速查

🎯小结：oMLX 让「在 Mac 上跑本地大模型」这件事变得像装一个 App 一样简单——菜单栏管理、SSD 缓存、多模型并发、OpenAI 兼容 API 全部开箱即用。装好、下载模型、打开 Chat，5 分钟即可拥有完全离线、数据不出本机的大模型推理服务。祝你使用愉快！

【免费下载链接】omlxLLM inference server with continuous batching & SSD caching for Apple Silicon — managed from the macOS menu bar项目地址: https://gitcode.com/GitHub_Trending/om/omlx