mlx-serving

Apple Silicon LLM 服务（MLX / oMLX）

在 Apple Silicon（M 系列）上运行和调优本地 LLM 推理的运维指南。涵盖两种常见后端：Apple 的 mlx-lm，以及基于 MLX 构建的 oMLX 服务。

两者都提供兼容 OpenAI 的 HTTP API，因此客户端代码可以通用。它们的差异体现在功能、打包方式，以及在统一内存接近上限时遇到的故障模式。

---

准备工作：验证环境

排查任何服务问题前，请先确认基本情况：

# Hardware: confirm Apple Silicon and unified-memory size
system_profiler SPHardwareDataType | grep -E "Model|Chip|Memory"

# Activate the venv where mlx-lm is installed before the next two probes,
# otherwise they hit system Python and may report nothing useful.
python -c "import mlx.core as mx; print(mx.__version__, mx.default_device())"
python -c "import mlx_lm; print(mlx_lm.__version__)"

# oMLX (DMG install): inspect available subcommands and run health checks
omlx --help
omlx diagnose menubar   # checks Tahoe ControlCenter visibility (oMLX-specific)

# Confirm a process is actually listening
lsof -nP -iTCP -sTCP:LISTEN | grep -E "omlx|mlx_lm"

排查前，请确认当前绑定的是哪个后端：两者都可以在用户指定的端口上提供兼容 OpenAI 的端点，而客户端请求若误打到另一个后端，可能会悄无声息地返回看似正确、实际无关的输出。

---

后端选择：mlx-lm 与 oMLX

方面	mlx-lm	oMLX
安装	pip install mlx-lm	DMG（macOS 应用包）
进程模型	每个 mlx_lm.server 进程运行一个模型	内置注册表；支持多模型
配置范围	最精简的 CLI 标志	丰富的单模型 JSON（model_settings.json）
功能标志	--temp、--top-p、基础功能	turboquant_kv、dflash、MTP、specprefill、思考预算
工具调用	格式取决于聊天模板	单模型解析器（可配置）
模型大于 RAM	不支持（加载时 OOM）	OptiQ 代理构建版本（基于敏感度的量化）
GUI	无	原生 macOS 应用 + 菜单栏
默认端口	8080	8000
最适用于	以库为主的脚本、嵌入 Python	长期运行的守护进程、多模型、GUI 运维

**技能侧重：**本文内容侧重 oMLX，深入介绍功能标志、缓存控制和上游 Bug 模式。对 mlx-lm 的介绍较少，重点在于两者共用的基础。

在以下情况选择 mlx-lm：你可以控制 Python 进程、希望尽量精简、一次只运行一个模型，并且模型能轻松装入 RAM。

在以下情况选择 oMLX：你需要一个在终端会话结束后仍能运行的守护进程、要通过一个端点运行多个模型、希望使用功能标志（turboquant、dflash、MTP）而不必自行编写，或者模型超出 RAM 容量且需要 OptiQ 代理。

两种后端都受相同的基本限制影响（统一内存、KV 缓存压力、模型架构特性），因此本文的大部分故障排查内容都适用于两者。

---

症状 → 原因排查

症状	可能原因	首要措施
模型加载期间 OOM	模型 + KV 临时空间超过可用 RAM	使用更小的量化版本；使用 OptiQ 代理（oMLX）；关闭其他应用以释放内存
长上下文推理期间 OOM	KV 缓存增长	启用 turboquant_kv；设置 --paged-ssd-cache-dir 将缓存溢出到 SSD（CLI 标志是实际生效的控制项；dflash_* 键是依版本而异的覆盖项）
batch > 1 时崩溃 / 卡死	架构缓存形状不匹配	固定 --max-concurrent-requests 1（oMLX）；参见 upstream-bug-patterns
工具调用以纯文本内容返回	解析器无法识别模型的工具调用 JSON 格式	参见 upstream-bug-patterns；检查响应中的 tool_calls 字段
更改配置后吞吐量下降	功能标志相互作用	使用基准测试逐项排查，每次只改一个标志
服务启动时卡住	从冷磁盘加载大型检查点	等待；持续查看 server.log；通过 iostat 检查磁盘 I/O
输出错误 / 乱码	量化过于激进，或聊天模板不正确	降低 turboquant_kv_bits 或禁用该功能；确认聊天模板与模型卡一致
第一次请求很慢，后续请求很快	前缀缓存未预热	启用 specprefill；用虚拟请求预热缓存
输出在句中截断	max_tokens 太低；思考预算已耗尽	提高 max_tokens；检查 thinking_budget_enabled

如需深入排查各类症状，请参见：references/symptoms.md。

---

核心原则

1. 对于批处理脆弱的架构，将 --max-concurrent-requests 降至 1。 oMLX 默认值为 --max-concurrent-requests 8。较高的并发度 会暴露特定架构的批处理问题（尤其是 Llama-4 使用的 ChunkedKVCache 等缓存实现）。对于受影响的架构，启动时将并发度 固定为 1；只有在确认 batch>1 时输出正常后，才逐步提高并发度进行 基准测试。

2. 一次只调整一个标志。 功能标志之间会相互影响（例如，dflash + turboquant_kv 都会影响 KV 缓存路径）。同时更改两个标志并观察到 回退时，将无法判断原因。每次更改之间都要进行基准测试。

3. 基准测试，不要猜测。 “感觉更快”不是调优依据。 维护一套小型基准测试集（聊天 / 编码 / 工具调用正确性 + 吞吐量），并在每次配置更改后重新运行。参见 references/bench-methodology.md。

4. 让聊天模板与模型卡保持一致。 工具调用和推理行为 取决于请求时应用的聊天模板。模型的 HuggingFace 卡片是权威依据。

5. 量化是一条曲线，而不是开关。 turboquant_kv_bits=4.0 可以保留大部分质量；更低的位数会以质量换取内存。基准测试集中务必包含 质量评估项——通过吞吐量测试但编码表现不佳的配置，可能不如速度较慢但结果正确的配置。

6. OptiQ 代理仅适用于“模型 > RAM”的情况。 它会构建一个由敏感度驱动的 模型代理，从而无需将完整模型载入内存，也能做出逐层量化决策。它并非通用的 加速手段；对于可载入内存的模型，它会增加启动开销，却不会带来运行时收益。

7. 服务端错误可能伪装成配置问题。 如果某个症状在多种配置组合下 都能复现，应怀疑上游问题，而不是继续尝试更多标志。参见 references/upstream-bug-patterns.md。

---

参考资料

• references/symptoms.md — 症状排查，包括 诊断和修复（OOM、batch>1 崩溃、工具调用被当作文本、吞吐量回退、 日志排查）
• references/omlx-feature-flags.md — 各标志参考（turboquant_kv、dflash、MTP、specprefill、思考 预算、max-concurrent-requests、force_sampling）及其相互影响
• references/bench-methodology.md — 基准测试，不要猜测：测试集设计、与后端无关的测试框架结构、 评分、变更归因
• references/upstream-bug-patterns.md — 判断应怀疑上游问题还是配置问题；两种反复出现的错误模式 （批处理调度下的缓存形状不匹配；模型工具调用格式未被解析）及其诊断和报告指南

---

此技能不涵盖的内容

• 云端大模型托管（Bedrock、OpenAI API、Anthropic API）——完全不同的 领域
• 非 MLX 本地后端（llama.cpp、Ollama、vLLM）——问题领域有重叠， 但使用的工具不同
• 模型训练、微调或 LoRA——请参阅 MLX 训练教程
• 与 MLX 无关的一般 Python / HTTP 调试
• 模型卡创建或 HuggingFace 上传工作流