@Prince_Canuma: mlx-vlm v0.6.4 来了！今天开始使用：> uv pip install -U mlx-vlm 5个新模型系列 — MiniMax M3、Kimi K2.5、Un…

mlx-vlm v0.6.4 来了！立即开始：> uv pip install -U mlx-vlm 新增 5 个模型系列——MiniMax M3、Kimi K2.5、Unlimited-OCR、DeepSeek V4、GLM 5.2 等。现在服务器自带原生 TTS/STT 端点，同时在 TurboQuant、连续批处理、M-RoPE 等方面进行了深度稳定性改进。共计 72 个 PR，18 位贡献者，其中 10 位首次贡献者。 01 · 性能（4 项改进） > Qwen3.5 在 CUDA 上：修复了仅限 Metal 的崩溃 + 分块门控增量预填充（预填充速度提升 8.5 倍） > 改进了 TurboQuant 预填充（预填充速度提升 2 倍至 26 倍）——@Alaxarr > 优化了 PaddleOCR-VL 视觉快速路径——scyyh11 > 消除了启动后首次请求时的完整模型重新加载——royteeuwen 02 · 服务器与 API > 服务器中新增 TTS 和 STT 端点——@lllucas > 支持多种模型类型的预加载——@lllucas > 改进了 Responses API 的推理和工具流事件——justin-schroeder > APC 前缀缓存现在可与 MTP 推测解码配合使用——vedang 03 · 扩散模型 > 扩散模型支持预填充策略——@lllucas > 修复了 Flux.2 模型中平铺 VAE 导致的颜色偏移——@lllucas > 修复了量化 Diffusion Gemma 的速度（速度提升 4 倍） 04 · 稳定性与修复 > 使 Qwen M-RoPE 在连续批处理下变为请求局部 > 合并了缓存 + RoPE 处理——@lllucas > 修复了 TurboQuant MTP 回滚尾部归零的问题 > 修复了量化 KV 缓存在掩码长度检查中的崩溃——@Alaxarr 05 · 新贡献者（10 位首次贡献者） 热烈欢迎我们的新贡献者：imi4u36d, kqw8, royteeuwen, raullenchai, Abdullah-Alharbi61, @Alaxarr, justin-schroeder, vedang, scaryrawr 请给我们一颗星：https://github.com/Blaizzy/mlx-vlm — # Blaizzy/mlx-vlm 来源：https://github.com/Blaizzy/mlx-vlm 上传 Python 包 (https://github.com/Blaizzy/mlx-vlm/actions/workflows/python-publish.yml) # MLX-VLM MLX-VLM 是一个用于在 Mac 上使用 MLX 进行视觉语言模型（VLM）和全能模型（支持音频和视频的 VLM）推理和微调的包。 ## 目录 - 安装 - 使用方法 - 命令行界面 (CLI) - 思考预算 - 推测解码 - DFlash (Qwen3.5) - Gemma 4 MTP - Gemma 4 EAGLE-3 - MiniMax M3 EAGLE-3 - 使用 Gradio 的聊天界面 - Python 脚本 - 服务器 (FastAPI) - 连续批处理 - 自动前缀缓存 (APC) - KV 缓存量化 - 激活量化 (CUDA) - 多图像聊天支持 - 支持的模型 - 使用示例 - 模型特定文档 - 视觉特征缓存 - TurboQuant KV 缓存 - 分布式推理 - 微调 ## 模型特定文档 部分模型提供了详细的文档，包含提示格式、示例和最佳实践： | 模型 | 文档 | |—––|—————| | DeepSeek-OCR | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/deepseekocr/README.md) | | DeepSeek-OCR-2 | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/deepseekocr_2/README.md) | | Unlimited-OCR | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/unlimited_ocr/README.md) | | DOTS-OCR | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/dots_ocr/README.md) | | DOTS-MOCR | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/dots_ocr/README.md) | | ERNIE 4.5 VL | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/ernie4_5_moe_vl/README.md) | | GLM-OCR | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/glm_ocr/README.md) | | Phi-4 Reasoning Vision | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/phi4_siglip/README.md) | | MiniCPM-o | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/minicpmo/README.md) | | PaddleOCR-VL | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/paddleocr_vl/README.md) | | Phi-4 Multimodal | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/phi4mm/README.md) | | MolmoPoint | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/molmo_point/README.md) | | LocateAnything | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/locateanything/README.md) | | Moondream2 | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/moondream2/README.md) | | Moondream3 | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/moondream3/README.md) | | Gemma 4 | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/gemma4/README.md) | | MiniMax M3 | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/minimax_m3_vl/README.md) | | Falcon-OCR | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/falcon_ocr/README.md) | | Granite Vision 3.2 | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/granite_vision/README.md) | | Granite 4.0 Vision | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/granite4_vision/README.md) | | MiniCPM-V 4.6 | 文档 (https://github.com/Blaizzy/mlx-vlm/blob/main/mlx_vlm/models/minicpmv4_6/README.md) | ## 安装 开始使用的最简单方法是使用 pip 安装 mlx-vlm 包： sh pip install -U mlx-vlm ## 使用方法 ### 命令行界面 (CLI) 使用 CLI 从模型生成输出： sh # 文本生成 mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "Hello, how are you?" # 图像生成 mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --temperature 0.0 --image http://images.cocodataset.org/val2017/000000039769.jpg # 音频生成（新功能） mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit --max-tokens 100 --prompt "Describe what you hear" --audio /path/to/audio.wav # 多模态生成（图像 + 音频） mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit --max-tokens 100 --prompt "Describe what you see and hear" --image /path/to/image.jpg --audio /path/to/audio.wav #### 思考预算 对于思考模型（例如 Qwen3.5），你可以限制思考块中使用的 token 数量： sh mlx_vlm.generate --model mlx-community/Qwen3.5-2B-4bit \ --thinking-budget 50 \ --thinking-start-token "" \ --thinking-end-token "" \ --enable-thinking \ --prompt "Solve 2+2" | 标志 | 描述 | |——|———––| | --enable-thinking | 在聊天模板中激活思考模式 | | --thinking-budget | 思考块内允许的最大 token 数 | | --thinking-start-token | 打开思考块的 token（默认：） | | `--thinking-end-token` | 关闭思考块的 token（默认：） | 当预算超支时，模型被迫生成 \n 并过渡到答案。如果传入了 --enable-thinking 但模型的聊天模板不支持它，则仅当模型自行生成开始 token 时才会应用预算。 在服务器上，思考模式默认禁用。使用 --enable-thinking 启动服务器，使其成为未指定该选项的请求的默认行为： sh mlx_vlm.server --model Qwen/Qwen3.5-4B --enable-thinking 你也可以为服务器设置思考预算和分隔符 token 的默认值： sh mlx_vlm.server --model Qwen/Qwen3.5-4B \ --enable-thinking \ --thinking-budget 512 \ --thinking-start-token "" \ --thinking-end-token "" 请求可以使用 enable_thinking、thinking_budget、thinking_start_token 或 thinking_end_token 覆盖服务器默认值。 ### 推测解码 通过使用一个小的“起草者”模型生成几个候选 token，并在单个目标前向传递中验证它们，从而加速生成。支持三种起草者系列。 | 标志 | 描述 | |——|———––| | --draft-model | 起草者的 HuggingFace 仓库或本地路径 | | --draft-kind | 起草者系列 — dflash（默认）、eagle3 或 mtp（原生/助手 MTP） | | --draft-block-size | 覆盖起草者配置的块大小 | 有关 Python API 示例（包括批量生成），请参见 docs/usage.md。 #### DFlash (Qwen3.5) 一个轻量级的块扩散起草者，每轮预测多个 token，通常快 2–3 倍。 sh # 使用推测解码进行文本生成 mlx_vlm.generate --model Qwen/Qwen3.5-4B \ --draft-model z-lab/Qwen3.5-4B-DFlash \ --prompt "Write a quicksort in Python." \ --max-tokens 512 --temperature 0 --enable-thinking # 也可用于图像 mlx_vlm.generate --model Qwen/Qwen3.5-4B \ --draft-model z-lab/Qwen3.5-4B-DFlash \ --image examples/images/cats.jpg \ --prompt "Describe this image." \ --max-tokens 256 --temperature 0 --enable-thinking # 使用推测解码的服务器 mlx_vlm.server --model Qwen/Qwen3.5-4B \ --draft-model z-lab/Qwen3.5-4B-DFlash DFlash 起草缓存窗口化可从 Python API 使用。在推测解码期间，目标模型仍会使用其完整 KV 缓存验证每个提议的 token；此旋钮仅更改 DFlash 起草者的缓存。当设置了 draft_window_size 时，起草者仅在其自身 KV 缓存中保留最多那么多最近的已提交 token，而不是关注整个生成的序列前缀。这减少了起草侧的缓存长度和内存，但由于起草者比目标验证器具有更少的上下文，因此可能会降低接受率。在 MLX 上，对于 Qwen3.5 DFlash，完整的起草缓存通常更快，因此窗口化默认为 None；仅当你想要试验这种紧凑的最近 token 缓存权衡时才设置它： python from mlx_vlm import load from mlx_vlm.generate import generate from mlx_vlm.speculative.drafters import load_drafter model, processor = load("Qwen/Qwen3.5-4B") draft_model, draft_kind = load_drafter("z-lab/Qwen3.5-4B-DFlash") draft_model.config.draft_window_size = 256 # None 禁用窗口化 result = generate( model, processor, "Write a quicksort in Python.", max_tokens=512, temperature=0, draft_model=draft_model, draft_kind=draft_kind, ) #### Gemma 4 MTP 多 token 预测 (https://ai.google.dev/gemma/docs/mtp/mtp)：Google 的 4 层“助手”起草者，与目标共享 K/V，并从恒定位置自回归地起草多个 token。传递 --draft-kind mtp 以调度 MTP 循环。 sh mlx_vlm.generate --model mlx-community/gemma-4-31B-it-bf16 \ --draft-model mlx-community/gemma-4-31B-it-assistant-bf16 \ --draft-kind mtp --draft-block-size 4 \ --prompt "Explain speculative decoding in 3 sentences." \ --max-tokens 256 --temperature 0 # 服务器 mlx_vlm.server --model mlx-community/gemma-4-31B-it-bf16 \ --draft-model mlx-community/gemma-4-31B-it-assistant-bf16 \ --draft-kind mtp --draft-block-size 4 支持的配对（目标 ↔ 起草者）： | 目标 | 起草者 | |———————————|——————————————| | mlx-community/gemma-4-E2B-it-bf16 | mlx-community/gemma-4-E2B-it-assistant-bf16 | | mlx-community/gemma-4-E4B-it-bf16 | mlx-community/gemma-4-E4B-it-assistant-bf16 | | mlx-community/gemma-4-26B-A4B-it-bf16 | mlx-community/gemma-4-26B-A4B-it-assistant-bf16 | | mlx-community/gemma-4-31B-it-bf16 | mlx-community/gemma-4-31B-it-assistant-bf16 | 测得的加速（贪婪解码，字节相同的输出）：在 B=4 时，26B-A4B 上最高 3.94×，31B 上最高 2.29×。有关完整扫描和架构说明，请参见 mlx_vlm/speculative/drafters/gemma4_assistant/README.md。 #### Gemma 4 EAGLE-3 EAGLE-3 (https://sgl-project.github.io/SpecForge/concepts/EAGLE3.html) 使用轻量级单层推测器，从三个目标隐藏状态捕获中起草。Red Hat Speculators 检查点自动检测为 --draft-kind eagle3。 sh mlx_vlm.generate --model mlx-community/gemma-4-31B-it-bf16 \ --draft-model RedHatAI/gemma-4-31B-it-speculator.eagle3 \ --prompt "Explain speculative decoding in 3 sentences." \ --max-tokens 256 --temperature 0 # 服务器 mlx_vlm.server --model mlx-community/gemma-4-31B-it-bf16 \ --draft-model RedHatAI/gemma-4-31B-it-speculator.eagle3 #### MiniMax M3 EAGLE-3 MiniMax M3 支持已发布的 Inferact/MiniMax-M3-EAGLE3 起草者。使用 mlx_vlm.convert 转换目标，因为 mlx_lm.convert 不知道 minimax_m3_vl 模型类型。 sh mlx_vlm.convert \ --hf-path MiniMaxAI/MiniMax-M3 \ --mlx-path ~/MiniMax-M3-4bit \ --quantize --q-bits 4 \ --trust-remote-code mlx_vlm.convert \ --hf-path Inferact/MiniMax-M3-EAGLE3 \ --mlx-path ~/MiniMax-M3-EAGLE3 mlx_vlm.generate \ --model ~/MiniMax-M3-4bit \ --draft-model ~/MiniMax-M3-EAGLE3 \ --draft-kind eagle3 \ --draft-block-size 3 \ --prompt "Explain MiniMax Sparse Attention in one paragraph." \ --max-tokens 256 --temperature 0 公共 MiniMax M3 BF16 检查点公布了 MTP 元数据，但未发布 mtp 或 nextn 张量，因此对于该检查点，请使用已发布的 EAGLE-3 起草者。MiniMax M3 还支持图像/视频提示、MiniMax 思考标签、MiniMax 工具调用解析、MSA 索引缓存和 MXFP8 配置加载。有关模型特定的转换和运行时说明，请参见 mlx_vlm/models/minimax_m3_vl/README.md。 ### 使用 Gradio 的聊天界面 使用 Gradio 启动聊天界面： sh mlx_vlm.chat_ui --model mlx-community/Qwen2-VL-2B-Instruct-4bit ### Python 脚本 以下是如何在 Python 脚本中使用 MLX-VLM 的示例： python import mlx.core as mx from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import load_config # 加载模型 model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit" model, processor = load(model_path) config = load_config(model_path) # 准备输入 image = ["http://images.cocodataset.org/val2017/000000039769.jpg"] # image = [Image.open("...")] 也可以使用 PIL.Image.Image 对象 prompt = "Describe this image." # 应用聊天模板 formatted_prompt = apply_chat_template( processor, config, prompt, num_images=len(image) ) # 生成输出 output = generate(model, processor, formatted_prompt, image, verbose=False) print(output) #### 音频示例 python from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import load_config # 加载支持音频的模型 model_path = "mlx-community/gemma-3n-E2B-it-4bit" model, processor = load(model_path) config = model.config # 准备音频输入 audio = ["/path/to/audio1.wav", "/path/to/audio2.mp3"] prompt = "Describe what you hear in these audio files." # 应用带有音频的聊天模板 formatted_prompt = apply_chat_template( processor, config, prompt, num_audios=len(audio) ) # 使用音频生成输出 output = generate(model, processor, formatted_prompt, audio=audio, verbose=False) print(output) #### 多模态示例（图像 + 音频） python from mlx_vlm import load, generate from mlx_vlm.prompt_utils import apply_chat_template from mlx_vlm.utils import load_config # 加载多模态模型 model_path = "mlx-community/gemma-3n-E2B-it-4bit" model, processor = load(model_path) config = model.config # 准备输入 image = ["/path/to/image.jpg"] audio = ["/path/to/audio.wav"] prompt = "" # 应用聊天模板 formatted_prompt = apply_chat_template( processor, config, prompt, num_images=len(image), num_audios=len(audio) ) # 生成输出 output = generate(model, processor, formatted_prompt, image, audio=audio, verbose=False) print(output) ### 服务器 (FastAPI) 启动服务器： ``sh mlx_vlm.server –port 8080 # 启动时预加载模型（Hugging Face 仓库或本地路径） mlx_vlm.server –model # 启动时预加载不同的模型类型 mlx_vlm.server –model \ –image-model \ –tts-model \ –stt-model # 使用适配器预加载模型 mlx_vlm.