Blaizzy/mlx-vlm

MLX‑VLM – Apple MLX 上での視覚言語モデルの推論とファインチューニング

何であるか – mlx‑vlm は、Apple の MLX フレームワークをサポートする Mac で、現代の視覚言語モデル（VLM）およびマルチモーダル「オムニ」モデル（画像 + 音声 + 映像）をローカルで実行・ファインチューニングできる Python パッケージです。CLI、FastAPI サーバー、Gradio チャット UI をバンドルし、モデル変換、量子化、推測的デコード用のユーティリティも提供します。

---

コア機能

機能	詳細
推論	mlx_vlm.generate はテキストのみ、画像、音声、または画像＋音声の組み合わせプロンプトをサポートします。
ファインチューニング	Hugging‑Face チェックポイントを MLX 形式に変換し、低ビット量子化（4ビット、1ビットアフィン、KVキャッシュ量子化）を適用するためのツール（mlx_vlm.convert、mlx_vlm.finetune – 本文では省略）
推測的デコード	3つのファミリーによるドラフトモデルベースの高速化：DFlash/DFlash2/DSpark、Gemma‑4 MTP、EAGLE‑3。ユーザーは --draft-model、--draft-kind、およびオプションのブロックサイズを指定します。
思考予算	「思考」ブロック（``）を出力するモデルに対して、その中で消費するトークン数を制限できます（--thinking-budget）。
サーバー / API	mlx_vlm.server は、連続バッチ処理、自動プレフィックスキャッシュ、KVキャッシュ量子化、マルチモーダルエンドポイント（LLM、画像生成、TTS、STT）をオプションで提供する FastAPI サービスを起動します。
チャット UI	1コマンドで起動可能な Gradio インターフェース（mlx_vlm.chat_ui）で、インタラクティブなマルチモーダルチャットが可能。
モデルズー	数十種類の VLM 用の即時実行可能なラッパー（例：Qwen2‑VL、Gemma‑4、MiniCPM‑o、Moondream 2/3、Granite Vision、LLaVA‑OneVision など）を提供。各モデルには README リンク付き。
エージェントスキルバンドル	コーディングアシスタント（Claude Code、Codex、Gemini）向けの準備済みプロンプトを含む skills/ ディレクトリ。変換、ベンチマーク、イシュー生成などの自動化タスクを支援。

---

クイックスタート（CLI）

# コアパッケージのインストール
pip install -U mlx-vlm
# オプション：Gradio UI 用の追加パッケージ
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

ドラフトモデルが1ステップあたり複数のトークンを提案し、ターゲットモデルが1回のフォワードパスで検証することで、大規模モデルでは最大約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 でワークフロー全体をカバー。

---

ヘルプの取得 / コントリビューション

• リポジトリには、コーディングアシスタントプラグイン（Claude Code、Codex、Gemini）向けの skills バンドルが付属。一般的な開発タスクを自動化。
• reproducible-github-issues スキルにより、イシューを再現可能な GitHub レポートに変換可能。
• コントリビューションは contributing スキルによりガイドされ、プリコミットフックやテスト配置のチェックが行われます。

---

TL;DR – mlx‑vlm は Apple の MLX を使用して Mac 上で視覚言語（および音声/映像）モデルの実行・ファインチューニングを行うためのフルスタックツールキット。豊富な CLI、Python API、サーバー、UI、および推測的デコードなどの高度な高速化機能を備えています。