mlx-vlm: Apple Silicon 上で VLM を推論・微調整するための Python パッケージ

Mac のローカルで VLM を動かすという具体的な問題

VLM を試すとき、多くの手順は NVIDIA GPU を前提にしている。Mac 上で完結させようとすると、モデルの重み形式、量子化、画像前処理のつなぎ込みを毎回自分で書くことになる。mlx-vlm はその部分を一つのパッケージにまとめたもので、README の冒頭では「inference and fine-tuning of Vision Language Models (VLMs) and Omni Models (VLMs with audio and video support) on your Mac using MLX」と説明されている。対象読者は、Mac のメモリに収まる範囲で視覚言語モデルを動かしたい開発者、および音声や動画も扱う Omni モデルを試したい開発者だ。クラウド API に画像を送りたくない、あるいはレイテンシを手元で測りたいという動機とも噛み合う。

MLX に載せ替える部分と、モデルごとに用意された実装

アーキテクチャとしては、MLX を計算バックエンドとして使い、モデルごとの実装を mlx_vlm/models 配下のディレクトリに分ける構成になっている。README のモデル別ドキュメント表には deepseekocr、phi4_siglip、minicpmo、paddleocr_vl、granite4_vision、llava_onevision、moondream3 などが並び、それぞれ models/<name>/README.md にプロンプト形式と例が置かれている。つまり共通の推論ループがあり、その上にモデル固有の前処理とプロンプト規約が乗る。この分離は対応モデルを増やしやすい反面、利用者から見ると「どのモデルがどの入力形式を期待するか」を個別に読む必要があることを意味する。OCR 系のモデルが独立したドキュメントを持つのは、入力の作り方が汎用のチャット系と大きく違うからだと読める。

導入と最初の生成: pip と mlx_vlm.generate

インストールは pip で完結する。README の記載は pip install -U mlx-vlm で、Gradio のチャット UI を使う場合だけ追加の依存が要るため pip install -U 'mlx-vlm[ui]' を使う。角括弧をシェルのグロブとして展開する zsh ではクォートが必要だと明記されている。推論は CLI から実行でき、テキスト生成の例として mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "Hello, how are you?" が、画像生成の例として同じモデルに --max を付ける形が README に載っている。モデルは mlx-community 配下の量子化済み重みを指定する流れで、自分で変換する場合は mlx_vlm.convert を使う。リポジトリには skills/ 以下にエージェント向けのスキル集も同梱され、cli-inference や convert-quantize といった単位でコマンドの使い方が整理されている。python3 skills/scripts/validate_skills.py でバンドルの検証ができる。

サーバとして使う場合の機能と、その代償

FastAPI ベースのサーバが同梱されており、README は continuous batching、automatic prefix caching (APC)、KV キャッシュ量子化を挙げている。複数リクエストをまとめて処理し、共通のプレフィックスを再利用し、キャッシュを圧縮するという三点は、単発の CLI 実行ではなくサービスとして動かすときに効いてくる。加えて投機的デコーディングの節があり、DFlash、DFlash2、DSpark、Gemma 4 MTP、Gemma 4 EAGLE-3、MiniMax M3 EAGLE-3 といった方式が列挙されている。ここは評価が分かれる部分で、方式ごとにモデル側の対応が必要であり、どのモデルでも同じ高速化が効くわけではない。README は方式名とモデル名の組み合わせを示しているだけで、汎用のスイッチがあるわけではないと読むべきだ。

見落としやすい制約: 対応表の外側と CUDA の記述

README には Activation Quantization (CUDA) という節がある。MLX は Apple Silicon 向けの枠組みなので、この見出しはやや意外に見える。少なくとも活性化量子化に関する記述が CUDA 文脈で語られており、Mac だけで完結する話ではないことがうかがえる。もう一つの制約は対応モデルの範囲そのものだ。モデル別ドキュメント表に名前があるモデルは手厚いが、表に無いモデルは mlx_vlm/models 以下に実装があるかを自分で確認し、無ければ追加することになる。skills に add-new-model が用意されているのは、この作業が日常的に発生するからだと推測できる。また、量子化済み重みの入手可否も別問題で、mlx-community に該当の変換済みモデルが無ければ mlx_vlm.convert を自分で回す必要がある。

比較対象としての llama.cpp 系と Transformers

同じ「ローカルで視覚言語モデルを動かす」目的には llama.cpp 系の実装がある。違いは量子化とモデル定義の持ち方で、llama.cpp は GGUF 形式に寄せて C++ 側でモデル定義を持つ。mlx-vlm は Python 側にモデル実装を持ち、MLX の配列演算に載せる。そのため新しいアーキテクチャへの追従は Python のクラスを足す形になり、学習や微調整まで同じリポジトリで扱える。逆に、GGUF エコシステムのツール群や、Python を挟まない配布を前提にしている場合は llama.cpp 側が自然だ。Hugging Face Transformers と MLX を自分で組み合わせる選択肢もあるが、その場合は画像前処理、量子化、キャッシュ、サーバの各層を自分で書くことになる。mlx-vlm はその層をまとめて提供する代わりに、対応モデルの一覧という形で利用可能な範囲が明示される。

微調整とアップグレードのコスト

README には Fine-tuning の節があり、推論だけでなく微調整も対象に含まれている。量子化されたモデルをそのまま学習に回すのか、変換前の重みを使うのかは README の抜粋からは判断できないため、実際に着手する前に該当節とモデル別ドキュメントを読む必要がある。更新頻度は高く、v0.7.0 が 2026-09-07、その前に v0.7.0rc0 が 2026-08-31、v0.6.17 が 2026-08-26 と、リリース候補を含めて短い間隔で版が上がっている。モデル追加のペースが速いということは、逆に言えば API や CLI フラグが版ごとに動く可能性を想定しておくべきだということでもある。ライセンスは MIT で、派生物の配布条件は緩い。ただし同梱されるモデル重みや Hugging Face 上のモデルはそれぞれ別のライセンスを持つため、業務利用の前にモデル側の条件を確認する必要がある。ここは法的助言ではなく、確認先の指摘にとどめる。

編集部の結論

Apple Silicon 上で量子化済み VLM をローカル推論させたい、あるいは FastAPI サーバとして自前のアプリに組み込みたい開発者には向いている。CUDA 前提のモデルや、対応表に載っていない新しいアーキテクチャをすぐ使いたい場合は、mlx_vlm/models 以下に該当ディレクトリがあるかを先に確認すべきで、無ければ変換から自分で書く前提になる。導入前に見るべきは、対象モデルの models/<name>/README.md にあるプロンプト形式と、mlx_vlm.convert で自分の重みが変換できるかどうかの2点。

公式情報源

1. Blaizzy/mlx-vlm on GitHub
2. Issues
3. License: MIT
4. README
5. Releases