当前 v0.11.0 版本
macMLX v0.11.0
当前版本让 macMLX 成为本地智能体后端:Codex 对接新的 /v1/responses,Claude Code 对接带 thinking 与 count_tokens 的 /v1/messages;回放的推理会传到聊天模板;在混合与滑动窗口模型上,智能体轮次会复用之前的历史;Xcode 27 与 Apple Foundation Models 客户端已做端到端核验;Gemma 4 E4B 与稠密 Qwen3.5/3.6 可以读图。
兼容性与升级说明
- 兼容性
- 新接口明确说明自身边界:/v1/responses 是无状态的,且逐个处理请求;Claude Code 的每个模型别名都必须映射到本地模型;端到端运行只覆盖 Xcode 27 在 Qwen3.6-27B 上、Apple Foundation Models 客户端在它与 Gemma 4 E4B 上,且不含图像;读图只适用于附带视觉塔的 E4B 形状 Gemma 4 检查点与稠密 Qwen3.5/3.6 检查点,图像请求不会在提示缓存中记录任何内容。多词元预测解码不属于这一版本。
- 升级
- 升级前请查看标签版 v0.11.0 更新日志。不带 max_tokens 或 max_completion_tokens 的 chat completion 现在最多可生成 32,768 个词元,而不是 2,048 个,连续批处理器的每行上限也随之升到 32,768;提供工具的请求现在一律走单流路径,但 tool_choice "none" 与 tools: [] 仍会批处理;chat completion 的回答现在从第一个非空白文本开始;/v1/messages 接受 tool_choice 的 none、any 与 tool(any 与 tool 提供全部工具但不强制调用),并以 Anthropic 的错误形状报告未知模型或加载失败;GET /v1/models 会列出模型目录中的每个聊天模型;视觉 Gemma 4 或 Qwen3.5/3.6 检查点此前以文本方式加载时留在 SSD 上的提示缓存条目会各未命中一次。
已交付
Apple 芯片 macOS 安装
macMLX 支持运行 macOS 14 或更高版本的 Apple 芯片 Mac。
请使用项目当前安装与 Gatekeeper 指南;不要仅为打开应用而关闭系统级安全保护。
核验
Swift 进程内推理
默认引擎在 Swift 进程内加载并运行 MLX 模型。
模型加载、生成、缓存与服务通过 MacMLXCore 使用 Apple MLX;默认推理路径不需要 Python 运行时。
核验
Apple 芯片统一内存
MLX 数组使用 Mac 的 CPU/GPU 共享内存系统。
统一内存减少 CPU 编排与集成 GPU 计算之间的显式传输,但模型权重、激活值和 KV 缓存仍会占用有限的物理内存。
核验
共享代码,进程内各自运行
应用与 CLI 都导入 MacMLXCore,推理和服务由核心负责。
两个产品共享实现与行为;当应用和 CLI 分别运行在不同进程时,它们不会共享同一个内存中引擎实例。
核验
默认路径无需 Python
已发布的默认引擎为 Swift 原生,不需要 Python 运行时。
可选兼容引擎可能使用子进程与其他运行时,因此这并不表示项目任何地方都没有 Python。
核验
OpenAI 端点兼容
聊天、传统补全、模型列表与嵌入使用兼容的请求和响应结构。
兼容范围按端点界定。/x/models 下的模型加载与卸载是 macMLX 扩展,不属于 OpenAI 兼容的模型管理。
核验
Anthropic Messages 兼容
v0.5.3 提供 POST /v1/messages,并支持流式响应。
这里只兼容 Messages API,不代表兼容完整 Anthropic API。
核验
部分 Ollama 端点
macMLX 支持 /api/version、/api/tags、/api/show、/api/chat 与 /api/generate。
该兼容层自 v0.3.7 起提供;它只覆盖选定端点,不是完整 Ollama API 的无差别替代。
核验
MCP 服务端
CLI 可向 MCP 客户端提供本地推理能力。
MCP 服务端在 v0.5.0 发布,与聊天侧调用外部工具的路由功能不同。
核验
MCP 客户端池
v0.5.3 包含受管理的 MCP 客户端连接。
客户端池负责管理外部 MCP 进程与连接;聊天侧集成工具路由是另一个在 v0.6.0 发布的能力。
核验
聊天集成工具路由
v0.6.0 为 OpenAI、Anthropic 与 GUI MCP 循环交付多轮工具路由。
各协议的验证明确约束工具调用历史;该路由与 MCP 服务端及客户端池基础设施不同。
核验
本地嵌入
POST /v1/embeddings 已在 v0.5.3 发布。
系统可以检测编码器模型家族,但若使用不合适的聊天模型,仍可能生成缺乏语义保证的向量。
核验
精确前缀 RAM 与 SSD 缓存
内存热层与内容寻址 SSD 冷层支持提升和降级。
v0.5.0 发布的缓存复用完整精确前缀,不包含已发布的块共享或分页 KV 分配。
核验
Trie 最长前缀复用
v0.6.0 可复用最长兼容缓存词元前缀。
多轮提示可裁剪到最长公共前缀,只增量预填充新增后缀,同时用量统计仍按完整提示计算。
核验
有界模型池
预算、LRU 淘汰、固定、冷切换、空闲 TTL 与探针共同约束多模型使用。
模型池在 v0.5.0 发布并于 v0.5.3 加固;它不是统一自适应控制器。
核验
受支持的 LoRA 适配器
原生引擎可应用受支持的 LoRA 适配器。
适配器兼容性取决于基础架构与权重,不宣称通用 LoRA 兼容。
核验
检测 14 个 VLM 家族
模型库可检测 14 个视觉语言 model_type 家族。
这是有证据支持的家族数量,不保证每个检查点或处理器变体都能加载。
核验
DeepSeek V3.2 Swift 覆盖层
v0.5.3 包含 DeepSeek V3.2 架构的纯 Swift 组件对齐实现。
真实检查点冒烟测试仍待完成,且缺少 FP8 反量化,因此不构成端到端或通用 MoE 声明。
核验
资格门控的连续批处理
v0.6.0 仅在真实并发下批处理符合条件的稠密文本请求,并自动回退到串行路径。
标签版 4 客户端基准测得 2.5–3.2× 聚合吞吐量;VLM、推测解码、Ollama、Anthropic 与嵌入仍保持串行。
核验
固定预填充准入节流
固定 prefillBatchSize 限制每个调度步骤接纳的行数。
已发布的节流采用固定配置,并非规划中的自适应内存控制器。
核验
结构化输出
v0.6.0 支持 response_format 的 json_object 与明确界定的 JSON Schema 子集。
不支持的 Schema 关键字返回 400;VLM 与结构化输出、工具与结构化输出都是不支持的组合,会被明确拒绝而非静默降级。
核验
推测解码
v0.6.0 通过 API 与 GUI 交付经典草稿模型路径。
接受率遥测用于呈现草稿效率;若目标使用不可裁剪的混合或线性注意力缓存,系统会检测并回退到标准解码。
核验
API 兼容功能包
v0.6.0 新增 logit_bias、logprobs 与 top_logprobs、XTC、逐请求 LoRA 适配器和 tools。
明确的兼容矩阵约束参数组合,不支持的配对返回 400,而不会静默降级。
核验
KV 缓存量化
v0.6.0 为兼容请求开放 kv_bits、kv_group_size 与 quantized_kv_start。
这些参数改变 KV 缓存精度,而非模型权重精度;非正数 kv_bits 会禁用该功能,兼容矩阵会拒绝不支持的模型或请求组合。
核验
Hugging Face 缓存发现
v0.6.0 可发现配置的 Hugging Face 缓存根目录中的模型,无需重复下载权重。
发现仅确认本地候选项,并不保证通用加载;架构、分词器、处理器与检查点兼容性仍然适用。
核验
Track G 已测试模型
v0.6.2 新增四个通过检查点实测的原生模型家族。
真实检查点生成实测:Seed-OSS-36B 4-bit 为 18.2 tok/s;Hunyuan V1 Dense 1.8B 4-bit 为 80.3 tok/s;Cohere Command R7B 7B 4-bit 为 21.7 tok/s;MiniCPM3-4B 4-bit 为 18.7 tok/s。结果仅适用于对应检查点,不构成整个家族的性能保证。
核验
InternLM3 理论支持
v0.6.2 交付通过等价性验证的 InternLM3 代码,支持等级为理论级。
真实生成尚未得到演示。公开检查点提供 tokenizer.model,但没有 tokenizer.json,而 Swift 分词器栈需要 tokenizer.json;在该加载路径边界改变前,支持仍为理论级。
核验
temperature 与 top-p
temperature 与核采样 top-p 是已发布参数。
它们是当前已开放的核心采样控制。
核验
硅活动面板
新的主窗口活动标签页显示实时 Apple 芯片读数、预填充/解码吞吐拆分,以及当前推理瓶颈与相应建议。
面板读取 GPU 占用、内存带宽、热与内存压力以及各电轨功耗,无需管理员权限或辅助进程。它是可观测性,而非性能保证:不可用的计数器会显示破折号并给出原因,空闲引擎显示无活动生成,估算值会被标注而非当作实测值。
核验
推理瓶颈分类器
v0.7.0 将硬件采样与引擎实时的预填充或解码阶段融合,归因限制生成的因素。
由于分类器在进程内运行,它知道当前处于哪个推理阶段——这是外部 GPU 监视器无法获取的信号。它是经过平滑的启发式判断,而非性能剖析器:优先级为内存高于热、热高于计算或带宽,应用迟滞与三帧平滑,并自校准带宽上限,因此结论是指引而非真值测量。
核验
免 sudo 的硅采样
运行时 IOReport 桥接与一组采样器读取 GPU 占用、内存带宽、热与内存压力以及 ANE 功耗。
IOReport 桥接通过 dlopen 解析,因此未来若某个 macOS 重命名或移除该私有框架,读数会降级为不可用而非无法启动。内存带宽以估算值呈现,ANE 提供功耗代理且不虚构利用率百分比,而无占空比信号的媒体引擎则被省略而非猜测。
核验
基准瓶颈归因
基准运行在生成过程中采样硅指标,并将限制其解码稳态的因素附加到保存的结果上。
归因给出解码限制项(内存、热、带宽或计算)及其置信度和背后的代表性硬件。过短而无法归因的运行会报告为不可用,而不是编造结论;低置信度或基于估算的判断会被标注。它描述的是一次实测运行,而非家族级基准保证。
核验
OCR 模型识别
专用 OCR 检查点会获得区别于通用 Vision 徽章的 OCR 徽章,且 GLM-OCR 已端到端验证。
GLM-OCR 通过原有 VLM 路径加载,无需新增模型代码,并能读回图像文字。该徽章刻意保持克制:仅出现在真正能加载的模型上,因此被检测到但尚未移植的 OCR 家族(如 dots_ocr 或 deepseek-ocr)不会获得徽章。这是模型识别,而非通用 OCR 质量声明。
核验
字节有界的冷 KV 层
v0.8.0 将磁盘冷 KV 缓存约束到明确的字节预算,按最旧优先清理,并提供关闭冷层的开关。
此前无上限的冷目录现遵循 Cold(SSD)预算,并同时接入 Hot(RAM)预算;首次启动时超出预算的目录会被裁剪,且只移除可再生的缓存,而非模型文件或设置。它并未新增块共享或分页分配;已发布的缓存仍只复用完整精确前缀。
核验
以权重身份守护的冷条目
v0.8.0 将每个冷条目与模型权重身份指纹绑定,使权重替换后无法再提供陈旧 KV。
指纹覆盖模型 config 及每个 safetensors 分片;若同一路径后续换成重新下载、重新量化或替换的权重,陈旧条目会被拒绝并删除,而不是恢复为静默错误的输出。它是冷层复用的完整性守护,而非对所有缓存路径的正确性证明,也不改变已发布的精确前缀复用语义。
核验
跨会话的持久冷索引
v0.8.0 持久化冷索引,使最长前缀复用可在重启后跨会话保留。
延续更早会话提示的后续轮次可直接从磁盘复用共享前缀;缺失、不可读或版本不匹配的索引会降级为精确命中,绝不会导致错误输出。复用仍为精确前缀,而非规划中的分页或块共享虚拟化;持久索引只是把既有的最长前缀复用延伸到进程重启之后。
核验
脱离 actor 的冷层写入器
v0.8.0 将冷层写入从缓存 actor 迁移到专用的串行后台写入器。
持久化被逐出的 KV 快照(大型缓存可达数百毫秒)不再阻塞其他请求的缓存查找;写入通过临时文件加重命名原子落盘,磁盘上的结果保持不变。它将磁盘写入迁出以保持存储 actor 的响应性,并不改变缓存内容或已发布的复用语义。
核验
进程内语音转文字与文字转语音
POST /v1/audio/transcriptions 与 POST /v1/audio/speech 在同一 Swift 进程内基于 MLX 运行。
音频引擎为 mlx-audio-swift,因此默认路径仍不需要 Python 运行时,也不绕道 Core ML,模型下载位于 ~/.mac-mlx/audio-models。若请求的输出容器 macMLX 无法生成,会直接拒绝,而不是改用其他格式充数。这些路径已完成代码并有单元测试,但尚未在真实音频检查点上验证,因此不对转写或合成质量作任何宣称。
核验
应用内的音频能力
转写以可取消的聊天附件形式提供,助手消息新增朗读按钮,模型库会列出音频检查点。
转写结果会落入输入框,便于发送前编辑;开始一次朗读会停止另一次。模型库需要独立扫描,因为 mlx-audio 采用扁平目录布局且常不附带 tokenizer.json,常规格式检测无法分类;两个调度注册表都查不到的检查点会被有意略过,而不是按文件夹名猜测类型。该接口尚未在真实音频检查点上验证。
核验
可检测的多词元预测草稿模型
草稿模型仅凭 config.json 即可在加载权重前被识别为 MTP 块草稿模型。
注册与检测已交付;引擎有意没有接线使用它们进行解码。这不是已发布的多词元预测解码,也不改变任何生成路径。
核验
应用已链接受控 MLX 构建
v0.9.0 是首个 GUI 真正链接 macMLX 自有补丁版 mlx-swift(而非上游版本)的 DMG。
Xcode 工程此前没有声明自己的 mlx-swift 依赖,因此在包 identity 冲突时,间接引入的上游副本获胜并被应用链接;此前每个版本发布的 GUI 都不包含那些 MacMLXCore 自身测试已逐条验证过的正确性 cherry-pick。CLI 因另一个 root 存在同样缺陷,已一并修复。这是把引擎恢复成原本预期的样子,而不是在其携带的修复之外改变推理行为。
核验
Foundation Models 形状的 JSON Schema
自 v0.10.0 起,结构化输出接受 Apple Foundation Models 客户端为 @Generable 类型发送的 Schema 形状:嵌套对象、带 minItems 与 maxItems 的数组、指向根 $defs 或 definitions 的 $ref、字符串 const、任意类型的根、任意 Unicode 字符串的键与字面量,以及数字与整数的 minimum 或 maximum 范围。
Schema 最多嵌套 32 层容器,$ref 展开后最多 4,096 个节点;递归 Schema 返回 400,null、联合类型、pattern 与 multipleOf 仍不支持。思考模型上的约束请求会以 enable_thinking 关闭渲染,且永远不会被报告为推理内容。v0.11.0 起,没有范围的 integer 会被限制在 64 位整数范围内,以保证总能解析,但范围内取什么值仍由模型决定。哪些 @Generable 类型经 Apple 客户端做过端到端运行,见 Xcode 27 与 Foundation Models 那条事实;此处接受某种 Schema 形状,本身并不等于经过验证的集成。
核验
流式用量、max_completion_tokens 与缓存词元
v0.10.0 支持 stream_options.include_usage,并在 [DONE] 之前发送一个仅含用量的分块;接受 max_completion_tokens 作为 max_tokens 的新写法;并报告提示缓存命中了多少提示。
缓存词元在 OpenAI 形状的响应中以 prompt_tokens_details.cached_tokens 呈现,在 /v1/messages 中以 cache_read_input_tokens 呈现,此时 input_tokens 为未命中缓存的剩余部分。未命中以及从不查询缓存的路径上该值为 0;由于它是精确前缀判定信号,带 Origin 请求头的请求不会得到该值。非流式请求会忽略 include_usage,因为其响应体本已包含用量。这里只涵盖这些用量字段,而非所有 OpenAI 流式选项。
核验
卸载即归还内存
v0.10.0 在释放聊天模型后清空 MLX 的缓冲区缓存,因此卸载、空闲清理或模型池淘汰会真正归还模型占用的内存,而不是把它留在缓存里。
在此版本之前,卸载 Mellum2-12B-A2.5B-Thinking-4bit 后,模型用过的 7,035 MB 中仍有 7,021 MB 留在 MLX 缓存里;改动后该缓存为空,仅剩 15 MB 活跃内存,几乎全部是提示缓存的内存层,而卸载不会释放这一层(默认最多 512 MiB)。这是对单个检查点的实测,并非对所有模型的保证。推测解码期间的取消可能让权重留待之后的清理,首次加载若在分配后失败,则留给下一次普通生成的清理。
核验
重排器与嵌入模型计入模型池预算
在应用中,服务端会在加载前把 /v1/rerank 与 /v1/embeddings 的模型纳入模型池,因此它们与聊天模型一样计入预算、按最近最少使用淘汰,并按模型的 TTL 过期。
切换时现在会先释放驻留的重排器或嵌入模型并清空 MLX 缓存,再在生成锁下加载替代模型。POST /x/models/unload 接受模型 id,并按该确切 id 卸载驻留的重排器或嵌入模型;既不是它们、也不是当前聊天模型的 id 现在返回 404,而不再无论如何都卸载聊天模型。CLI 的服务端没有模型池,仍直接加载它们;模型标签页也不再提供固定它们的选项。/x/models 仍是 macMLX 扩展,不属于 OpenAI 兼容的模型管理。
核验
基于 MLXRerankers 的重排
v0.10.0 通过 mlx-swift-lm 的 MLXRerankers 提供 POST /v1/rerank:BERT、RoBERTa 与 XLM-RoBERTa 交叉编码器,按 yes/no logit 差打分的 Qwen3 重排器,以及 Jina reranker v3。
在真实检查点上实际运行过的:ms-marco-MiniLM-L-6-v2 在关闭 TF32 时与 PyTorch fp32 参考在 logit 尺度上相差 2e-6 以内,在 M5 默认启用的 TF32 矩阵乘下相差 0.025 以内;Qwen3-Reranker-0.6B-4bit 会把回答问题的文档排在不回答的文档之前。XLM-RoBERTa 路径(BGE)与 Jina v3 尚未在真实检查点上运行,且 Jina v3 报告的是余弦相似度而非概率。分类头的判定比上游规则更窄,因此情感分类头仍是普通模型;对非重排检查点,双编码器余弦仍是回退路径。
核验
原生检查点聊天模板
v0.10.0 通过 swift-jinja 2.5.1 渲染每个检查点自带的聊天模板,并移除两个内置覆盖;逐模型的 macmlx.chat_template.jinja 文件仍优先生效。
提示会在用户可能察觉的地方变化:tojson 现在在工具描述中输出 Python json.dumps 风格的结果,带 {#- 与 -#} 注释的模板按 Jinja 的方式渲染空白,带 answer 标签的 Hunyuan 历史轮次按 Python 的方式剥离。请求携带 tools 时 Command R7B 现在会渲染其 tool_use 模板,但 macMLX 没有解析其所要求动作标记的解析器,因此不支持该模型的工具调用。模板支持仍非通用。
核验
基于 mlx-swift 0.32.3 的受控 MLX fork
v0.10.0 将受控 MLX fork 变基到 mlx-swift 0.32.3(core v0.32.2);该基线已包含 fork 此前携带的十三条修复中的十二条,因此 fork 现在自带五条:mlx#3922、mlx#4009、mlx#4660、mlx#4431 与 mlx#4775。
mlx#4009 修复了排序后的量化 MoE 乘积在 M5 硬件上、group size 为 32 且 K 不规整时破坏 92–97% 输出的问题。mlx#4660 防止卷积的通道填充在异步求值下混入错误数值,Qwen-VL 系列与 GLM-OCR 的 3 通道 patch embedding 都会走到这条路径;mlx#4775 修正量化 KV cache 中全负分组的缩放;mlx#4431 修复一个批量长上下文注意力核,目前没有任何 macMLX 路径会选中它。每一条在携带前都已用合成测试在本机复现,均未通过真实检查点复现。新基线还修复了 JIT 下量化 MoE gather 核的名称(mlx#4372),并按 macOS 27 要求的 Metal 4.1 语言版本编译内核。mlx-swift-lm 随之升至 3.32.3,预填充分块固定为旧的 .remainder 步长,这一点是通过阅读代码而非输出比对确认的;上游单独重写的 Gemma3Text 预填充不在覆盖范围内。携带修复是正确性修补,而非性能宣称。
核验
音频下载保留在应用缓存中
借助受控的 mlx-audio-swift fork(上游 v0.1.5 加上缓存与列表修复),此前会向 ~/.cache/huggingface 再下载一份的语音家族现在从 ~/.mac-mlx/audio-models 加载,缓存快照也会依据 Hub 的完整文件列表补全。
仍会下载到默认 Hugging Face 缓存的有:从本地目录而非按仓库 id 加载的模型所用的分词器或编解码器、Kokoro 与 Kitten 的字素转音素模型,以及非英语 Kokoro 音色的 byT5 模型或词典。v0.9.0 留在那里的副本不会被删除;尚未经 Hub 列表确认的快照无法离线补全。音频加载现在在生成锁下进行,因此加载器自行发起的下载可能阻塞其他请求。这里没有任何测试运行音频推理;只有 moonshine-tiny、带 SNAC 编解码器的 VyvoTTS 与 SenseVoiceSmall 的门控缓存冒烟测试通过,因此不对转写或合成质量作任何宣称。
核验
DMG 交付经过测试的依赖图
v0.10.0 提交了应用工作区的 lockfile,发布归档、CLI 压缩包与应用 CI 构建只使用各自 lockfile 记录的版本;若应用或 CLI 的 lockfile 对 MacMLXCore 所钉包的版本不同,CI 会失败。
v0.9.0 的归档在全新 runner 上解析依赖,交付了 swift-jinja 2.4.2,而所有聊天模板测试都运行在 2.3.6 上。这只是把依赖版本钉到测试实际使用的版本,并非可复现构建或代码签名的宣称,DMG 仍未签名。
核验
OpenAI Responses API
v0.11.0 提供 POST /v1/responses,Codex 等使用 Responses API 的客户端可以对 macMLX 运行其智能体循环:文本、流式推理、函数工具与自定义工具、多轮工具结果、通过 text.format 的结构化输出,以及包含提示缓存命中的用量。
它是无状态的:不存储任何响应,store 会被忽略,previous_response_id、item_reference 条目、background 与文件 id 返回 400,因此客户端每轮都要发送完整对话,Codex 正是如此。web_search 等托管工具不会提供给模型,会被忽略而不是拒绝;none 以外的 tool_choice 与 parallel_tool_calls 只回显、不强制;图像必须是 base64 data URL;请求逐个处理,因此 Codex 子智能体会排队而不是并行运行。这是 Codex 所用的 Responses 接口,而非完整的 OpenAI Responses API。
核验
/v1/messages 上的 Claude Code
v0.11.0 为 /v1/messages 增加 thinking,把模型的推理以 thinking 块返回,并新增 POST /v1/messages/count_tokens,返回 /v1/messages 据以生成的提示长度,因此 Claude Code 可以对接 macMLX 运行。
thinking 设为 disabled 会关闭思考模板的 enable_thinking,budget_tokens 会被接受但不强制。count_tokens 会像生成一样加载模型,并排在正在运行的生成之后。Claude Code 发送而 macMLX 不处理的字段,如 output_config、context_management、metadata 与 cache_control,会被接受并忽略。Claude Code 的每个模型别名都必须映射到本地模型,否则它会请求 claude-* id,macMLX 对此返回 404。这仍是 Messages API 兼容,而非完整的 Anthropic API。
核验
推理内容回传
当客户端在 chat completions、/v1/messages 或 /v1/responses 中回放之前助手轮次的推理时,v0.11.0 会把它作为该轮的 reasoning_content 传给聊天模板,让思考模型在工具循环中看到自己的推理。
渲染与否由模板决定:Qwen3.x、Mellum2 与 Gemma 4 的模板只为最后一个用户问题之后的轮次渲染它(Gemma 4 只在其中带工具调用的轮次渲染),因此遇到新问题时,提示缓存的复用会回退到上一个问题的末尾。承载它的 encrypted_content 与 signature 字段只是 macmlx.r1. 前缀后的 base64 文本,并非加密。走原有视觉路径的模型与 Ollama 端点不在范围内;不带回放推理的请求渲染结果与以前完全相同。
核验
混合与滑动窗口模型上的历史复用
在缓存含线性注意力层或滑动窗口层的模型上(如 Qwen3.6 或 Mellum2),v0.11.0 还会在对话历史末尾存一份缓存,下一轮智能体请求便能复用这段历史,而不必把整段对话重新预填充。
在 Qwen3.6-27B-4bit 上,1.7k 词元工具循环的第二轮复用了 1,712 个提示词元中的 1,662 个,耗时 1.0 秒,冷启动同一提示则为 2.8 秒;Mellum2 复用了 1,632 个中的 1,594 个。这些都是单次实测,并非对其他模型或提示的保证。历史增量不足 256 个词元的轮次不建立快照;大于 512 MiB 内存层的快照写入 SSD 层;缓存全由普通或量化注意力层组成、且没有滑动窗口层的模型不建立快照,仍像以前一样通过裁剪复用。这是精确前缀复用,而非分页 KV 或块共享。
核验
Xcode 27 与 Foundation Models 端到端核验
为 v0.11.0,在 Qwen3.6-27B-4bit 上让真实运行的 macmlx serve 接在 Xcode 27 的本地托管模型提供方之后,并在 Qwen3.6-27B-4bit 与 Gemma 4 E4B 上接在 Apple 的 ChatCompletionsLanguageModel 之后:Xcode 会列出已下载的模型并能持续对话,respond、streamResponse、多轮会话、工具、贪心采样,以及所核验 @Generable 类型的引导生成均可工作。
GET /v1/models 现在列出模型目录中的每个聊天模型,因为 Xcode 会把空列表视为连接失败;带 Origin 请求头的请求仍只看到已加载的模型。@Guide(.pattern) 返回 400;在思考模型上,贪心采样可能一直循环推理直到上限。未核验:图像、其他模型、没有运行服务时应用看到什么,以及 Ollama 端点;除这些运行之外,不对生成质量作任何宣称。
核验
Gemma 4 E4B 与稠密 Qwen3.5/3.6 读图
v0.11.0 会把附带视觉塔的 E4B 形状 Gemma 4 检查点或稠密 qwen3_5 检查点作为视觉模型加载,并在文本生成路径上提供服务,因此其图像请求仍保留提示缓存、工具调用、结构化输出、logprobs 与推理回传。
检查点必须带有视觉配置、视觉塔权重、匹配的处理器元数据,并符合其对齐验证所覆盖的形状才会被识别;31B 稠密版与 26B-A4B 的 Gemma 4、E2B、gemma4_unified、qwen3_5_moe 以及其他任何检查点仍像以前一样按文本加载。图像请求只复用到第一张图像为止的提示缓存,不记录任何缓存,也从不推测解码,因此带图像的智能体会话在之后每一轮都会从该图像起重新预填充。对齐验证是在 gemma-4-e4b-it-8bit、Qwen3.6-27B-4bit 与 Qwen3.5-4B-MLX-8bit 上对照其文本加载完成的,不构成对其他检查点的宣称;Qwen3.5/3.6 读取图像中小字的效果也较差。
核验
当前限制
资格门控的连续批处理
v0.6.0 仅在真实并发下批处理符合条件的稠密文本请求,并自动回退到串行路径。
标签版 4 客户端基准测得 2.5–3.2× 聚合吞吐量;VLM、推测解码、Ollama、Anthropic 与嵌入仍保持串行。
核验
结构化输出
v0.6.0 支持 response_format 的 json_object 与明确界定的 JSON Schema 子集。
不支持的 Schema 关键字返回 400;VLM 与结构化输出、工具与结构化输出都是不支持的组合,会被明确拒绝而非静默降级。
核验
InternLM3 理论支持
v0.6.2 交付通过等价性验证的 InternLM3 代码,支持等级为理论级。
真实生成尚未得到演示。公开检查点提供 tokenizer.model,但没有 tokenizer.json,而 Swift 分词器栈需要 tokenizer.json;在该加载路径边界改变前,支持仍为理论级。
核验
DeepSeek V3.2 Swift 覆盖层
v0.5.3 包含 DeepSeek V3.2 架构的纯 Swift 组件对齐实现。
真实检查点冒烟测试仍待完成,且缺少 FP8 反量化,因此不构成端到端或通用 MoE 声明。
核验
免 sudo 的硅采样
运行时 IOReport 桥接与一组采样器读取 GPU 占用、内存带宽、热与内存压力以及 ANE 功耗。
IOReport 桥接通过 dlopen 解析,因此未来若某个 macOS 重命名或移除该私有框架,读数会降级为不可用而非无法启动。内存带宽以估算值呈现,ANE 提供功耗代理且不虚构利用率百分比,而无占空比信号的媒体引擎则被省略而非猜测。
核验
进程内语音转文字与文字转语音
POST /v1/audio/transcriptions 与 POST /v1/audio/speech 在同一 Swift 进程内基于 MLX 运行。
音频引擎为 mlx-audio-swift,因此默认路径仍不需要 Python 运行时,也不绕道 Core ML,模型下载位于 ~/.mac-mlx/audio-models。若请求的输出容器 macMLX 无法生成,会直接拒绝,而不是改用其他格式充数。这些路径已完成代码并有单元测试,但尚未在真实音频检查点上验证,因此不对转写或合成质量作任何宣称。
核验
应用内的音频能力
转写以可取消的聊天附件形式提供,助手消息新增朗读按钮,模型库会列出音频检查点。
转写结果会落入输入框,便于发送前编辑;开始一次朗读会停止另一次。模型库需要独立扫描,因为 mlx-audio 采用扁平目录布局且常不附带 tokenizer.json,常规格式检测无法分类;两个调度注册表都查不到的检查点会被有意略过,而不是按文件夹名猜测类型。该接口尚未在真实音频检查点上验证。
核验
可检测的多词元预测草稿模型
草稿模型仅凭 config.json 即可在加载权重前被识别为 MTP 块草稿模型。
注册与检测已交付;引擎有意没有接线使用它们进行解码。这不是已发布的多词元预测解码,也不改变任何生成路径。
核验
Foundation Models 形状的 JSON Schema
自 v0.10.0 起,结构化输出接受 Apple Foundation Models 客户端为 @Generable 类型发送的 Schema 形状:嵌套对象、带 minItems 与 maxItems 的数组、指向根 $defs 或 definitions 的 $ref、字符串 const、任意类型的根、任意 Unicode 字符串的键与字面量,以及数字与整数的 minimum 或 maximum 范围。
Schema 最多嵌套 32 层容器,$ref 展开后最多 4,096 个节点;递归 Schema 返回 400,null、联合类型、pattern 与 multipleOf 仍不支持。思考模型上的约束请求会以 enable_thinking 关闭渲染,且永远不会被报告为推理内容。v0.11.0 起,没有范围的 integer 会被限制在 64 位整数范围内,以保证总能解析,但范围内取什么值仍由模型决定。哪些 @Generable 类型经 Apple 客户端做过端到端运行,见 Xcode 27 与 Foundation Models 那条事实;此处接受某种 Schema 形状,本身并不等于经过验证的集成。
核验
基于 MLXRerankers 的重排
v0.10.0 通过 mlx-swift-lm 的 MLXRerankers 提供 POST /v1/rerank:BERT、RoBERTa 与 XLM-RoBERTa 交叉编码器,按 yes/no logit 差打分的 Qwen3 重排器,以及 Jina reranker v3。
在真实检查点上实际运行过的:ms-marco-MiniLM-L-6-v2 在关闭 TF32 时与 PyTorch fp32 参考在 logit 尺度上相差 2e-6 以内,在 M5 默认启用的 TF32 矩阵乘下相差 0.025 以内;Qwen3-Reranker-0.6B-4bit 会把回答问题的文档排在不回答的文档之前。XLM-RoBERTa 路径(BGE)与 Jina v3 尚未在真实检查点上运行,且 Jina v3 报告的是余弦相似度而非概率。分类头的判定比上游规则更窄,因此情感分类头仍是普通模型;对非重排检查点,双编码器余弦仍是回退路径。
核验
原生检查点聊天模板
v0.10.0 通过 swift-jinja 2.5.1 渲染每个检查点自带的聊天模板,并移除两个内置覆盖;逐模型的 macmlx.chat_template.jinja 文件仍优先生效。
提示会在用户可能察觉的地方变化:tojson 现在在工具描述中输出 Python json.dumps 风格的结果,带 {#- 与 -#} 注释的模板按 Jinja 的方式渲染空白,带 answer 标签的 Hunyuan 历史轮次按 Python 的方式剥离。请求携带 tools 时 Command R7B 现在会渲染其 tool_use 模板,但 macMLX 没有解析其所要求动作标记的解析器,因此不支持该模型的工具调用。模板支持仍非通用。
核验
音频下载保留在应用缓存中
借助受控的 mlx-audio-swift fork(上游 v0.1.5 加上缓存与列表修复),此前会向 ~/.cache/huggingface 再下载一份的语音家族现在从 ~/.mac-mlx/audio-models 加载,缓存快照也会依据 Hub 的完整文件列表补全。
仍会下载到默认 Hugging Face 缓存的有:从本地目录而非按仓库 id 加载的模型所用的分词器或编解码器、Kokoro 与 Kitten 的字素转音素模型,以及非英语 Kokoro 音色的 byT5 模型或词典。v0.9.0 留在那里的副本不会被删除;尚未经 Hub 列表确认的快照无法离线补全。音频加载现在在生成锁下进行,因此加载器自行发起的下载可能阻塞其他请求。这里没有任何测试运行音频推理;只有 moonshine-tiny、带 SNAC 编解码器的 VyvoTTS 与 SenseVoiceSmall 的门控缓存冒烟测试通过,因此不对转写或合成质量作任何宣称。
核验
OpenAI Responses API
v0.11.0 提供 POST /v1/responses,Codex 等使用 Responses API 的客户端可以对 macMLX 运行其智能体循环:文本、流式推理、函数工具与自定义工具、多轮工具结果、通过 text.format 的结构化输出,以及包含提示缓存命中的用量。
它是无状态的:不存储任何响应,store 会被忽略,previous_response_id、item_reference 条目、background 与文件 id 返回 400,因此客户端每轮都要发送完整对话,Codex 正是如此。web_search 等托管工具不会提供给模型,会被忽略而不是拒绝;none 以外的 tool_choice 与 parallel_tool_calls 只回显、不强制;图像必须是 base64 data URL;请求逐个处理,因此 Codex 子智能体会排队而不是并行运行。这是 Codex 所用的 Responses 接口,而非完整的 OpenAI Responses API。
核验
Xcode 27 与 Foundation Models 端到端核验
为 v0.11.0,在 Qwen3.6-27B-4bit 上让真实运行的 macmlx serve 接在 Xcode 27 的本地托管模型提供方之后,并在 Qwen3.6-27B-4bit 与 Gemma 4 E4B 上接在 Apple 的 ChatCompletionsLanguageModel 之后:Xcode 会列出已下载的模型并能持续对话,respond、streamResponse、多轮会话、工具、贪心采样,以及所核验 @Generable 类型的引导生成均可工作。
GET /v1/models 现在列出模型目录中的每个聊天模型,因为 Xcode 会把空列表视为连接失败;带 Origin 请求头的请求仍只看到已加载的模型。@Guide(.pattern) 返回 400;在思考模型上,贪心采样可能一直循环推理直到上限。未核验:图像、其他模型、没有运行服务时应用看到什么,以及 Ollama 端点;除这些运行之外,不对生成质量作任何宣称。
核验
Gemma 4 E4B 与稠密 Qwen3.5/3.6 读图
v0.11.0 会把附带视觉塔的 E4B 形状 Gemma 4 检查点或稠密 qwen3_5 检查点作为视觉模型加载,并在文本生成路径上提供服务,因此其图像请求仍保留提示缓存、工具调用、结构化输出、logprobs 与推理回传。
检查点必须带有视觉配置、视觉塔权重、匹配的处理器元数据,并符合其对齐验证所覆盖的形状才会被识别;31B 稠密版与 26B-A4B 的 Gemma 4、E2B、gemma4_unified、qwen3_5_moe 以及其他任何检查点仍像以前一样按文本加载。图像请求只复用到第一张图像为止的提示缓存,不记录任何缓存,也从不推测解码,因此带图像的智能体会话在之后每一轮都会从该图像起重新预填充。对齐验证是在 gemma-4-e4b-it-8bit、Qwen3.6-27B-4bit 与 Qwen3.5-4B-MLX-8bit 上对照其文本加载完成的,不构成对其他检查点的宣称;Qwen3.5/3.6 读取图像中小字的效果也较差。
核验
规划中
分页 KV、块共享与 CoW
分页分配、共享块与写时复制分支处于规划阶段。
这些缓存虚拟化能力均未发布;已交付的缓存仅复用精确的 token 前缀(裁剪至最长公共前缀),没有共享块。
核验
统一自适应内存守卫
跨缓存、模型池与并发的反馈控制器处于规划阶段。
已发布的内存探针和模型池上限是独立机制,不能称为该守卫。
核验
扩展采样控制
top-k、min-p、presence、frequency 与 repetition 惩罚项,以及逐请求 seed 处于规划阶段。
DeepSeek 专家路由 top-k 是架构内部操作,与用户采样 top-k 无关。
核验
官方来源
- macMLX v0.11.0 · github.com
- Apple 芯片 macOS 安装
- 卸载即归还内存
- Apple 芯片统一内存
- Xcode 27 与 Foundation Models 端到端核验
- macMLX v0.11.0 · github.com
- MCP 客户端池
- 聊天集成工具路由
- 本地嵌入
- 以权重身份守护的冷条目
- Trie 最长前缀复用
- 重排器与嵌入模型计入模型池预算
- Track G 已测试模型
- DeepSeek V3.2 Swift 覆盖层
- 固定预填充准入节流
- 资格门控的连续批处理
- Foundation Models 形状的 JSON Schema
- 推测解码
- KV 缓存量化
- macMLX v0.11.0 · github.com
- InternLM3 理论支持
- temperature 与 top-p
- 硅活动面板
- 硅活动面板
- 推理瓶颈分类器
- 推理瓶颈分类器
- 免 sudo 的硅采样
- 免 sudo 的硅采样
- 基准瓶颈归因
- 基准瓶颈归因
- OCR 模型识别
- 字节有界的冷 KV 层
- 以权重身份守护的冷条目
- 跨会话的持久冷索引
- 脱离 actor 的冷层写入器
- 音频下载保留在应用缓存中
- 进程内语音转文字与文字转语音
- 应用内的音频能力
- 应用内的音频能力
- 可检测的多词元预测草稿模型
- 应用已链接受控 MLX 构建
- 音频下载保留在应用缓存中
- Foundation Models 形状的 JSON Schema
- Foundation Models 形状的 JSON Schema
- 基于 MLXRerankers 的重排
- 原生检查点聊天模板
- DMG 交付经过测试的依赖图
- DMG 交付经过测试的依赖图
- OpenAI Responses API
- OpenAI Responses API
- /v1/messages 上的 Claude Code
- 推理内容回传
- 混合与滑动窗口模型上的历史复用
- 混合与滑动窗口模型上的历史复用
- Xcode 27 与 Foundation Models 端到端核验
- Gemma 4 E4B 与稠密 Qwen3.5/3.6 读图
- Gemma 4 E4B 与稠密 Qwen3.5/3.6 读图
- 扩展采样控制
- 扩展采样控制