oMLX Welcome 引导界面 3 步详解：模型目录、启动服务器与首次下载完整教程
【免费下载链接】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是一款面向 Apple Silicon（M1–M5 芯片 Mac）的本地 LLM 推理服务器，支持连续批处理、SSD 分级缓存，并能直接从 macOS 菜单栏管理。对于新手来说，最大的门槛其实是第一次运行——而 oMLX 的Welcome 引导界面正是为此设计的：三步走，完成模型目录设置、启动服务器、下载第一个模型，全程无需打开终端。
本文带你完整走一遍这三步，5 分钟内跑起自己的本地大模型服务。
第一步：设置模型目录与端口（Initial Configuration）
首次启动 oMLX，会弹出Welcome to oMLX引导窗口，第一屏就是「Step 1 Initial Configuration」，需要确认 4 个字段：
| 字段 | 默认值 | 说明 |
|---|---|---|
| Base Directory | ~/.omlx | 基础目录，oMLX 的配置、日志、缓存都放在这里 |
| Model Directory | ~/.omlx/models | 模型文件存放目录，可指向你已下载的 MLX 模型所在目录 |
| Port | 8000 | 服务器监听端口，仅当端口被占用时才需要修改 |
| API Key | 空 | 至少 4 位、不能含空格的 ASCII 字符；它同时也是 Web 仪表盘登录密码，可点图标随机生成 |
💡两个实用细节：
- Base Directory和Model Directory都可以点
Browse...用系统文件选择器选目录； - 如果你已经用其他工具下载过 MLX 模型，把Model Directory指过去即可，oMLX 会自动识别子目录中的 LLM、VLM、Embedding 和 Reranker 模型。
向导会做实时校验：端口必须在 1–65535 之间，API Key 太短或含空格都会即时给出红色错误提示，避免带着错误配置继续往下走。
这一步的源码实现在 apps/omlx-mac/Sources/Welcome/WelcomeWindow.swift，其中validateStorage()与validateApiKey()就是上面这些校验规则的来源。
第二步：一键启动服务器（Start Server）
配置无误后，点击「Step 2 Start Server」区域的Start Server按钮，oMLX 会自动完成一连串后台动作：
- 写入配置：把目录、端口、API Key 持久化到
~/.omlx/settings.json，后续启动不再需要重复设置； - 定位 Python 运行时：App 内置了完整的 Python 环境（venvstacks 分层打包），无需自己装依赖；
- 启动服务器进程：默认绑定
127.0.0.1（只监听本机，不暴露到网络），端口冲突会直接在界面上提示，改个端口点一次即可； - 等待健康检查通过：向导会轮询
/health接口确认服务就绪后，才进入下一屏。
整个过程界面上会显示 “Starting Server...”，几秒后跳转到成功页（“All set!”）。此时你可以看到 oMLX 图标出现在菜单栏，随时Start/Stop Server、查看Serving Stats或打开Admin Panel，全程零终端操作。
⚠️ 注意：如果还没点 Start Server 就关闭了引导窗口，oMLX 会把它视为“取消”而不是“部分完成”——不会写入任何配置，下次启动会重新进入引导页。想重来就再打开 App 即可。
第三步：首次下载模型（Model Downloader）
成功页点击Open Web Dashboard，浏览器会打开http://127.0.0.1:8000/admin/dashboard，用你刚设置的 API Key 登录。接下来就能完成「首次模型下载」：
- 进入左侧导航的Model Downloader页面；
- 在Search HuggingFace输入框搜索（如
Qwen3.5），或直接从列表浏览推荐模型； - 点开感兴趣的项目，查看模型卡片、文件列表与磁盘占用；
- 点击Download一键下载，文件自动存入第一步配置的 Model Directory。
下载完成后模型会被自动发现并出现在 Models 页面，即可加载、固定（Pinning）、配置 TTL 或直接开聊。
仪表盘首页会实时展示服务状态与性能指标——缓存命中 token 数、缓存效率、提示词处理（PP）与文本生成（TG）速度一目了然：
常见问题速答
Q：端口 8000 被占用了怎么办？在引导页把 Port 改成 8001 等可用端口再点 Start Server；已启动后可在 Web 仪表盘 Settings 中修改。
Q：想改回默认目录怎么办？向导里的目录字段可以留空——留空即表示使用~/.omlx下的默认模型目录，而不是持久化一个空路径。
Q：下载慢/网络受限？服务器支持配置 HuggingFace 镜像端点（--hf-endpoint），可在命令行启动时指定国内镜像地址加速下载。
Q：以后还能重新看引导页吗？能。只要~/.omlx/settings.json存在，启动时就会跳过 Welcome 页，日常通过菜单栏或 Web 仪表盘管理即可。
总结：3 步跑通本地 LLM 服务
| 步骤 | 操作 | 结果 |
|---|---|---|
| 1️⃣ 模型目录 | 确认 Base/Model Directory、端口、API Key | 配置写入~/.omlx/settings.json |
| 2️⃣ 启动服务器 | 点 Start Server | 本机127.0.0.1:8000推理服务就绪 |
| 3️⃣ 首次下载 | 仪表盘搜索 + 一键 Download | 第一个 MLX 模型自动就绪 |
之后，任何 OpenAI 兼容客户端（以及 Claude Code、OpenClaw、Cursor 等编码工具）都可以直接指向http://localhost:8000/v1开始使用。配合 oMLX 的热/冷分级 KV 缓存，重复的长上下文不会每次从头重算——这正是它把本地大模型做到“日常可用”的关键。
更多细节可参考项目文档目录 docs/ 与源码 apps/omlx-mac/Sources/Welcome/。
【免费下载链接】omlxLLM inference server with continuous batching & SSD caching for Apple Silicon — managed from the macOS menu bar项目地址: https://gitcode.com/GitHub_Trending/om/omlx
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
