# mlx-engine - LM Studio官方MLX推理引擎（多轮缓存+批量读图）

> LM Studio跑MLX模型的官方引擎：多轮对话缓存命中秒回、同图追问只算一次视觉编码。99%的人不用装（LM Studio自带），自建MLX服务的值得抄它的缓存设计。

LM Studio 官方开源的 MLX 推理引擎——Apple MLX 栈之上的服务化封装。先说清层次：它不是 MLX 的竞品，而是 `mlx-lm`（文本）+ `mlx-vlm`（视觉）之上的增强层，Mac 版 LM Studio 0.3.4+ 已预打包。单独拎出来看，是因为它有两个 MLX 原生生态里少见的自研设计。

## 架构：站在巨人肩上

```
MLX（Apple 数组框架）
 ├─ mlx-lm     ← 文本推理、KV 量化（2/3/4/6/8bit）
 ├─ mlx-vlm    ← 视觉模型推理
 └─ mlx-engine ← 本仓库：服务化封装 + 自研缓存体系
```

## 自研点一：多轮 prompt 缓存恢复

普通 MLX 推理每轮对话都重新 prefill 全部历史。mlx-engine 的 `cache_wrapper` 做了一套 **checkpoint 机制**：

- 多轮对话按阶段存快照（LRU 保留 N 份历史）
- 新请求进来先匹配**最长公共前缀**，命中就直接恢复缓存，只 prefill 增量部分
- 服务重启后也能从磁盘 checkpoint 续

系统提示词长、多轮轮次多的场景（Agent、长对话助手），TTFT 差距是秒级 vs 毫秒级。

## 自研点二：批量视觉路径

`mlx-vlm` 本身是单请求库，mlx-engine 在其上做了 **batched vision**：

- 多请求并发读图，KV cache 批量化（BatchKVCache / RotatingKVCache）
- **图像特征记忆**（`vision_feature_memoizer`）：同一张图多轮追问，视觉编码只算一次
- 双层 prompt 缓存协调器：hot 内存层 + 磁盘层，带 disk budget 和 restore planner，显存紧张时自动往磁盘挪
- Qwen-VL 的 M-RoPE 位置编码专门打了 patch，长图上下文有 context fit 自适应

## 其他能力

- **投机解码**：大模型 + 小草稿模型加速（文本路径）
- **结构化输出**：集成 Outlines，JSON schema 约束生成
- **KV cache 量化**：2-8 bit 可调，省显存换长上下文

## 怎么用

99% 的人不用装：Mac 版 LM Studio 0.3.4+ 自带，下载模型就能用。想看源码或二开（比如把这套缓存架构搬进自己的 MLX 服务）再 clone：

```bash
git clone https://github.com/lmstudio-ai/mlx-engine
pip install -U -r requirements.txt   # Python 3.11
python demo.py --model mlx-community/Qwen2.5-7B-Instruct-4bit
```

适合谁：LM Studio Mac 用户（理解它为什么快）、自建 MLX 服务的开发者（`prompt_cache/coordinator.py` 和 `vision_feature_memoizer.py` 的设计值得抄）、想给本地 Agent 加多轮缓存的人。

---

**分类**：MacOS
**标签**：缓存 · mlx · MLX
**作者**：子龙
**链接**：https://octohz.com/p/2164