vMLX 是一款面向 Apple Silicon 的本地 AI 推理引擎，本文带你完整拆解 vMLX 源码架构：它如何用 Python FastAPI 引擎承载 OpenAI 兼容推理服务，用 Electron 桌面端管理模型会话，再用 Metal 内核在 GPU 上完成最终计算，三层各司其职、分层协作。

一张图看懂 vMLX 的整体分层

vMLX 的仓库结构非常清晰，顶层就是一个"桌面应用 + Python 引擎 + 测试集"的三段式布局：

一次推理请求的完整旅程是：Electron 主进程启动 Python 引擎子进程 → FastAPI 接收 HTTP 请求 → EngineCore 调度与缓存 → MLX 调用 Metal 内核在 GPU 上计算 → 流式结果沿原路返回前端。下面逐层拆解。

第一层：Python FastAPI 推理引擎

打开 vmlx_engine/ 目录，最关键的三个入口文件是：

• cli.py：vmlx serve、vmlx convert等命令的起点，也是桌面端实际拉起的服务入口；
• server.py：基于 FastAPI 的统一 OpenAI 兼容 API 服务，提供/v1/chat/completions、/v1/messages（Anthropic 格式）、/v1/images/generations等端点；
• engine_core.py：借鉴 vLLM 的 EngineCore 架构，负责模型加载、请求调度和异步流式输出。

两套推理引擎：单用户与并发各取所需

engine/ 目录实现了两种引擎，由--continuous-batching参数切换：

api/ 子目录则是一组"协议适配器"：anthropic_adapter.py 把 Anthropic Messages 请求翻译成内部格式，ollama_adapter.py 兼容 Ollama CLI，streaming.py 统一处理 SSE 流式输出。这正是桌面端 API 标签页可以直接展示多套协议代码片段的原因：

五层缓存：vMLX 性能的隐藏支柱

引擎层的另一个主角是缓存体系，核心文件包括 prefix_cache.py、paged_cache.py、disk_cache.py 和 block_disk_store.py，构成"内存 → 磁盘"两级回退：

请求 -> Tokens L1: 内存前缀缓存（Memory-Aware / Paged） L2: 磁盘缓存（Disk Cache / Block Disk Store） 未命中 -> 推理生成 float16 KV 状态 KV 量化（q4/q8）-> 存回 L1 + L2

前缀缓存让多轮对话的重复上下文秒级命中，磁盘缓存则让 KV 状态在服务器重启后依然可用。

第二层：Electron 桌面端 MLX Studio

panel/ 目录是 macOS 桌面应用 MLX Studio，标准 Electron 三进程结构：

engine-manager.ts 的工作方式是：探测系统中vmlx/vmlx-serve/vmlx-engine三种入口（覆盖 uv、pipx、pip 等安装方式），然后以子进程方式拉起 Python 引擎，通过健康检查确认就绪，再管理其整个生命周期。api-gateway.ts 则在本机 8080 端口做统一路由——同时加载多个模型时，一个 URL 就能按模型名访问所有服务，还能直接对接 Ollama CLI。

前端提供 Chat / Server / Tools / Image / API 五个模式。Chat 标签页支持思考模式、流式输出与工具调用：

Agentic 模式下模型可以调用工具完成完整编码任务，输出结构化代码：

Image 标签页则把 mflux 图像生成引擎（Flux Schnell/Dev、Z-Image Turbo、Qwen Image Edit 等）包装成可视化服务管理界面：

第三层：Metal GPU 内核

计算最终落在 MLX 框架的 Metal 后端，而 vMLX 在 vmlx_engine/metal/ 目录下自研了大量针对特定模型家族的融合内核。该目录包含两类文件：

• .metal源文件（如 codebook_moe.metal、affine_moe_decode.metal）：手写 Metal Shading 语言内核；
• .py配套文件：通过 MLX 的mx.fast.metal_kernelAPI 在内核与 Python 张量之间做数据编排，例如 kernel_manager.py 管理码本 VQ MoE 的融合 matvec 内核。

命名能看出针对性极强：qwen4_*系列优化 Qwen4 的 MoE 与 GDN 前缀计算，glm5_*系列覆盖 GLM5 的 MLA 注意力与解码路径，nax_*、sdpa_flash_decode.py等则处理通用注意力与稀疏索引。这种"一个模型家族一组内核"的策略，是 vMLX 对不同模型都能榨出硬件极限的关键。

此外 vmlx_engine/jangtq2/、jangh/、jangt/ 三个目录实现了 JANGQ 自适应混合精度格式的运行时反量化内核——注意力层保 8-bit、MLP 层压到 2-bit，让 2-bit 量化模型的 MMLU 得分远超同体积的 MLX 4-bit。

模型转换工具链：把任意模型变成 MLX 格式

除了推理，vMLX 还自带完整的量化转换工具。桌面端 Tools 标签页（对应引擎侧的vmlx convert命令）支持两种格式：

• MLX Uniform：标准 4/8-bit 均匀量化；
• JANG：自适应混合精度档位（JANG_2S到JANG_6M），按注意力/嵌入/MLP 分别设定位宽。

源码阅读路线建议

如果你是第一次读 vMLX 源码，推荐这条由浅入深的路径：

1. cli.py→server.py：看 HTTP 请求如何进入引擎；
2. engine_core.py→scheduler.py：理解请求调度与流式输出；
3. engine/的 SimpleEngine vs BatchedEngine：对比两种吞吐策略；
4. vmlx_engine/metal/：挑一个qwen4_开头的内核看融合实现；
5. panel/src/main/engine-manager.ts：从前端视角回看整个分层。

vMLX 源码架构的核心思想可以概括为一句：Electron 管"面子"（会话与进程），FastAPI 管"里子"（协议与调度），Metal 内核管"底子"（GPU 极限性能）——三层通过 HTTP 与子进程边界解耦，你甚至只安装 Python 引擎就能获得 90% 的能力，这种分层正是它值得借鉴的设计。