Blaizzy/mlx-vlm

MLX‑VLM – 在 Apple MLX 上进行视觉-语言模型的推理与微调

是什么 – mlx‑vlm 是一个 Python 包，可在支持 Apple 的 MLX 框架的 Mac 上本地运行和微调现代视觉-语言模型（VLM）及多模态“全能”模型（图像 + 音频 + 视频）。它捆绑了 CLI、FastAPI 服务器和 Gradio 聊天 UI，还包含一系列用于模型转换、量化和推测解码的工具。

---

核心功能

功能	详情
推理	mlx_vlm.generate 支持纯文本、图像、音频或图像+音频组合提示。
微调	工具（mlx_vlm.convert、mlx_vlm.finetune – 摘录中未显示）用于将 Hugging‑Face 检查点转换为 MLX 格式并应用低比特量化（4 位、1 位仿射、KV 缓存量化）。
推测解码	基于草稿模型的加速技术，支持三类：DFlash/DFlash2/DSpark、Gemma‑4 MTP、EAGLE‑3。用户指定 --draft-model、--draft-kind 和可选的块大小。
思考预算	对于输出“思考”块（``）的模型，可限制其内部消耗的 token 数量（--thinking-budget）。
服务器 / API	mlx_vlm.server 启动一个 FastAPI 服务，支持可选的连续批处理、自动前缀缓存、KV 缓存量化以及多模态端点（LLM、图像生成、TTS、STT）。
聊天 UI	一键式 Gradio 界面（mlx_vlm.chat_ui）用于交互式多模态聊天。
模型库	提供数十种 VLM 的即用型封装（例如 Qwen2‑VL、Gemma‑4、MiniCPM‑o、Moondream 2/3、Granite Vision、LLaVA‑OneVision 等），每个模型附带独立 README 链接。
代理技能包	包含 skills/ 目录，提供为编码助手（Claude Code、Codex、Gemini）准备的现成提示，可自动化常见任务如转换、基准测试或问题生成。

---

快速开始（CLI）

# 安装核心包
pip install -U mlx-vlm
# 可选 UI 额外包（用于 Gradio）
pip install -U 'mlx-vlm[ui]'

# 文本生成
mlx_vlm.generate \
  --model mlx-community/Qwen2-VL-2B-Instruct-4bit \
  --prompt "Hello, how are you?" \
  --max-tokens 100

# 图像生成
mlx_vlm.generate \
  --model mlx-community/Qwen2-VL-2B-Instruct-4bit \
  --image http://images.cocodataset.org/val2017/000000039769.jpg \
  --prompt "Describe this image." \
  --max-tokens 100

# 音频感知模型
mlx_vlm.generate \
  --model mlx-community/gemma-3n-E2B-it-4bit \
  --audio /path/to/audio.wav \
  --prompt "What do you hear?" \
  --max-tokens 100

---

推测解码示例（加速）

mlx_vlm.generate \
  --model Qwen/Qwen3.5-4B \
  --draft-model z-lab/Qwen3.5-4B-DFlash \
  --draft-kind dflash \
  --prompt "Write a quicksort in Python." \
  --max-tokens 512 \
  --temperature 0

草稿模型每步提出多个 token，目标模型通过单次前向传播验证，使大模型生成速度最高可达约 4 倍提升。

---

Python 使用（最小示例）

from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template

model, processor = load("mlx-community/Qwen2-VL-2B-Instruct-4bit")
prompt = "Describe this image."
image = ["http://images.cocodataset.org/val2017/000000039769.jpg"]
formatted = apply_chat_template(processor, model.config, prompt, num_images=1)
output = generate(model, processor, formatted, image)
print(output)

相同 API 也适用于音频或图像+音频输入。

---

服务器部署

# 简单启动（默认端口 8080）
mlx_vlm.server

# 预加载特定模型
mlx_vlm.server --model mlx-community/Qwen2-VL-2B-Instruct-4bit

# 全局启用思考模式
mlx_vlm.server --model Qwen/Qwen3.5-4B --enable-thinking

服务器公开文本生成、多模态生成以及可选的 TTS/STT 模型端点。

---

为何重要

• Apple 优先 – 利用 MLX 运行时，无需 CUDA 即可在 Apple Silicon GPU 上高效运行。
• 广泛多模态支持 – 支持视觉、音频、视频输入，以及图像生成输出。
• 性能优化技巧 – 推测解码、KV 缓存量化、1 位仿射推理在设备上带来显著的速度与内存提升。
• 开发者友好 – CLI、Python API、FastAPI 服务器、Gradio UI 覆盖整个工作流。

---

获取帮助 / 贡献

• 仓库附带 skills 包，用于编码助手插件（Claude Code、Codex、Gemini），可自动化常见开发任务。
• 可通过 reproducible-github-issues 技能将问题转化为可复现的 GitHub 报告。
• 贡献由 contributing 技能引导，检查预提交钩子和测试位置。

---

TL;DR – mlx‑vlm 是一个全栈工具包，用于在使用 Apple MLX 的 Mac 上运行和微调视觉-语言（及音频/视频）模型，具备丰富的 CLI、Python API、服务器、UI 以及推测解码等高级加速功能。