ローカルLLMで画像入力するには？ mmprojとランタイムの確認方法

画像を扱えるモデルをダウンロードしても、GGUF本体だけでは画像入力が使えないことがある。マルチモーダルLLMでは、モデルの機能だけでなく、projectorやmmprojなどの補助ファイルとランタイム側の対応までそろえる必要があるためだ。

確認するときは、使いたい入力形式 → モデル本体 → 補助ファイル → テンプレート → ランタイムの順で見ると原因を切り分けやすい。

まず画像・音声・動画のどれを使うか決める

「マルチモーダル」は、テキスト以外の情報も扱うモデルをまとめた呼び方だ。画像入力に対応するモデルが、音声や動画にも同じ方法で対応するとは限らない。

たとえばGemma 4 12B ITはモデルカード上でテキスト・画像・音声・動画入力を案内している。一方、実際にどの入力形式をローカルで利用できるかはランタイム側の実装にも依存する。

最初に必要なのが画像なのか、音声なのか、動画なのかを決めることで、確認すべき補助ファイルと実行経路を絞れる。

モデル本体だけでは足りない場合がある

画像入力を扱うモデルでは、画像をモデルが利用できる表現へ変換するprojectorが必要になる場合がある。GGUF系の配布ではmmprojという名前の補助ファイルを見かけることが多い。

llama.cppのマルチモーダル文書でも、モデル本体とは別にprojectorを指定する実行経路が案内されている。

重要なのは、mmprojという名前なら何でも組み合わせられるわけではないことだ。

• モデルの系列
• モデルのリビジョン
• 本体とprojectorの配布元
• 補助ファイルの形式
• tokenizerやprocessor
• チャットテンプレート

これらが対応する組み合わせになっている必要がある。

別モデル用のmmprojは流用しない

同じQwen系、Gemma系といった近い名前でも、別モデルや別リビジョン向けのprojectorをそのまま流用できるとは限らない。

モデル本体だけ新しい版へ更新し、古いmmprojを残した場合も不整合の原因になり得る。そのため、本体とprojectorは配布ページ上で対応関係を確認して選びたい。

コミュニティ配布を使う場合は、元モデル、リビジョン、量子化に加えて、mmprojがどの本体向けに作られているかも確認する必要がある。

ランタイム側がそのモデルに対応しているか確認する

モデルカードに画像入力と書かれていても、ランタイムがそのアーキテクチャのマルチモーダル経路を実装していなければ利用できない。

llama.cppを使う場合は、現在のバージョンが対象アーキテクチャを扱えるか、projectorを指定するオプションがその版で使えるかを確認する。

概念的には次のようにモデル本体とprojectorを指定する経路になる。

llama-server -m model.gguf --mmproj projector-file.gguf

実際のオプション名や対応アーキテクチャはバージョンによって変わり得るため、利用するリリースのドキュメントと--helpを基準にする。

LM StudioやOllamaでも、同じGGUFとmmprojを置けばllama.cppと同じように動くとは限らない。各アプリがそのモデルとマルチモーダル入力をどの経路で扱うか確認する必要がある。

テキスト起動と画像入力成功は別

モデル本体がテキストで正常に応答しても、画像入力まで成功したとは限らない。

切り分けるなら、まずモデル本体をテキストだけで起動する。次に対応するprojectorを追加し、小さな画像を1枚だけ渡す。その後で複数画像や長い入力へ広げる方が原因を追いやすい。

画像を渡した時点で失敗する場合は、モデル本体よりprojector、テンプレート、入力形式、ランタイム対応を重点的に確認できる。

逆に、画像入力が成功しても、大きな画像や動画、複数入力で必要なメモリや速度が同じとは限らない。ここは実際の利用条件で別に確認する必要がある。

必要メモリもテキストだけの場合とは同じとは限らない

マルチモーダル処理ではモデル本体だけでなく、画像などの入力処理にも追加のメモリや計算が必要になる。

そのため、テキストだけでモデルがGPUへ収まったという情報から、画像入力でも同じメモリ条件で動くとは断定できない。モデルファイルやmmprojの容量を足しただけでピークVRAMを算出することもできない。

GPUを選ぶ前に、使いたい入力形式が手元のランタイムで実際に動くことを確認する方が先になる。

うまく動かないときの確認順

マルチモーダルLLMで画像などを扱えない場合は、次の順で確認すると整理しやすい。

1. そのモデルが目的の入力形式に対応しているか
2. 本体の正確なモデル・リビジョンは何か
3. 対応するprojector/mmprojが必要か
4. 本体と補助ファイルの組み合わせが合っているか
5. ランタイムの現在のバージョンがそのアーキテクチャをサポートしているか
6. 必要なテンプレートやprocessorがそろっているか

GGUF全般の互換性が疑わしい場合は、GGUFはLM Studio・Ollama・llama.cppでどこまで互換？で形式とモデル対応を分けて確認できる。配布物自体を選び直す場合はGGUFモデルをダウンロードする前に確認したい5項目も参考になる。

「multimodal」と書かれていることは出発点であり、ローカルでの動作保証ではない。必要な入力形式、本体、補助ファイル、ランタイムの4つが同じ経路でそろっているかを見ることで、画像入力などが使えない原因を切り分けやすくなる。