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，以及推測解碼等高階加速功能。