MLX LMのPrompt Cache入門：長文を再利用する

先に結論

MLX LMのPrompt Cacheは、毎回同じ長い資料や指示を読む代わりに、その共通prefixをcache fileへ保存して次の質問で使う機能です。Apple SiliconでMLX LMを使う場合、長文の前半が完全に同じである作業だけに絞ると、何を再利用しているかを追いやすくなります。短い一回限りの質問、prefixが毎回変わる会話、RAMに収まらないmodelには、まず通常実行のまま戻すのが安全です。

確認日時: 2026年8月8日（Asia/Tokyo）
対象: MLX LMの現行READMEとv0.31.3 release（2026年4月22日公開、commit ed1fca4）
検証区分: 公式資料を基にした机上調査・最短手順です。この制作環境ではmlx_lmを実行しておらず、速度、memory使用量、出力品質は実測していません。
前提: Apple Silicon Mac、MLX LMを導入済みであること。大きなmodelをRAMに対して使う場合、公式READMEはmacOS 15以降を要件として案内しています。

Prompt Cacheで保存するものを決める

ここでいうprefixは、質問の前に毎回共通で渡す部分です。たとえば規約、固定した資料、同じsystem instructionです。質問ごとに変わる依頼文や最新の入力までcacheへ混ぜると、再利用できる範囲が小さくなり、何を見せたかも追跡しづらくなります。

MLX LMのREADMEでは、mlx_lm.cache_promptでpromptをcache fileへ保存し、mlx_lm.generateの—prompt-cache-fileで使います。cacheは後から渡すpromptの前に付くprefixとして扱われ、model指定はcacheから読まれるため、再利用時に別modelを混ぜないことが重要です。

最初は次の三つだけを用意してください。

内容を公開・保存してよい共通資料だけを入れたshared-prefix.txt
作業専用の空ディレクトリ
cacheの作成に使うmodel IDとMLX LMのversionを記録するメモ

API key、個人情報、顧客データ、別案件の資料を「便利だから」と共通prefixへ足さないでください。cache fileは入力の代替ではなく、保存対象として扱います。

最短手順：共通prefixを保存して質問する

公式READMEの構文に沿った最小例です。model IDは手元で許可済みのMLX対応modelへ置き換えます。コマンドを実行する前に、cache fileの保存先と入力ファイルの権限を確認してください。

cat shared-prefix.txt | mlx_lm.cache_prompt \
  --model "mlx-community/Llama-3.2-3B-Instruct-4bit" \
  --prompt - \
  --prompt-cache-file shared-prefix.safetensors

次に、保存したprefixの続きだけを渡します。

mlx_lm.generate \
  --prompt-cache-file shared-prefix.safetensors \
  --prompt "\n上の資料の要点を3項目で整理してください。"

成功確認は、まず次の順で行います。

shared-prefix.safetensorsが意図した作業場所へ作成されたことを確認する
二つ目のcommandが—prompt-cache-fileを指定して完了し、質問への応答を返すことを確認する
cache作成時と再利用時のMLX LM version、model、共通prefixのhashを同じメモへ残す
共通prefixを1文字でも変えたら、既存cacheを更新せず新しい名前で作り直す

「2回目が速い」だけでは、cacheの効果を証明できません。network download、model warm-up、CPU負荷も時間に影響します。性能を比較したい場合は、条件を固定するMLX LMのKV Cache再利用を評価する設計へ進んでください。

つまずきやすい点と戻し方

cacheと違うmodelで使おうとした

READMEでは、cacheを使うとmodelはcacheから読まれます。再利用commandへ別のmodel名を足して推測で合わせず、cacheを作ったときのmodel ID、MLX LM version、入力の先頭を確認します。どれかが不明ならcache fileを隔離し、同じmodelで新規作成してください。

回答に必要な前提が足りない

cacheは「保存した共通prefix」を補うだけです。質問ごとに必要な差分、日付、出典、制約は二つ目の—promptへ明示します。以前の質問への回答そのものを必要とする場合は、必要部分を新しいprefixへ含めるか、通常の完全promptへ戻します。

RAMが苦しい、または長文の品質が落ちる

MLX LMには固定サイズのrotating KV cacheもあり、—max-kv-sizeを小さくするとRAMを抑えられる一方、公式READMEは品質が悪化し得ると説明しています。Prompt Cacheとrotating KV cacheを同じ機能だと扱わず、最初は—max-kv-sizeを追加しない通常条件へ戻してください。大きなmodelを無理に常駐させるより、より小さいmodelまたは短い共通prefixで再確認します。

cache fileを共有してしまった

保存対象が不適切だった可能性がある場合は、そのcacheを再利用せず、アクセス可能な場所から外します。元の共通prefixを見直し、保存してよい内容だけで新しいcacheを作成します。cache名を上書きして履歴を失わないことも、原因調査に役立ちます。

次に進む条件

同じmodel、同じ共通prefix、同じ質問で通常実行とcache再利用を比較できるようになって初めて、時間とmemoryの評価へ進めます。Apple Siliconでmodel全体のmemory余白を先に決めたい場合は、Macのメモリ別ローカルLLM選びも併読してください。

参考資料

MLX LM公式repository：Long Prompts and Generations（2026年8月8日確認）
MLX LM公式repository：v0.31.3 Release Notes（2026年4月22日公開、2026年8月8日確認）