MLX LMのKV Cache再利用を評価する設計

先に結論

MLX LMのPrompt Cacheを評価するときは、cacheを使ったかどうかだけで速さを比べません。同じmodel、同じ共通prefix、同じ質問、同じMLX LM versionを固定し、prefillに要した時間、全体時間、memory、失敗率を別々に記録します。prefixが一致しない処理や、rotating KV cacheで長文の状態を捨てる処理では、同じ比較表に入れずに分けます。

確認日時: 2026年8月8日（Asia/Tokyo）
対象version: MLX LM v0.31.3（2026年4月22日公開、commit ed1fca4）をrelease基準にし、現行READMEのPrompt Cacheと--max-kv-sizeの説明を照合。
検証区分: 公式仕様による机上調査・測定計画です。本稿には実測値、benchmark結果、実行logはありません。
適用外: model品質の優劣、複数requestの最適スケジューリング、cache fileの互換性を将来versionへ保証すること、macOSのwired memory上限の変更手順。

再利用とKV上限を別の変数にする

MLX LMのREADMEが案内するPrompt Cacheは、保存したpromptを次のpromptのprefixとして使い、同じ長い文脈の再計算を避けるための仕組みです。一方、—max-kv-sizeはrotating fixed-size KV cacheの上限です。小さい値はRAMを抑える可能性がある反面、公式READMEは品質が悪化し得ると明記しています。

したがって、次の二つを同じ「cacheが有効」という列にまとめません。

比較対象	固定する条件	変える変数	主な観測
Prompt Cache再利用	model、共通prefix、質問、sampling、MLX LM version	cache fileの有無	prefill時間、全体時間、RSS／memory pressure、出力の形式一致
rotating KV cache	model、全prompt、質問、sampling、MLX LM version	`—max-kv-size`	memory、品質確認、全体時間、失敗率

Prompt Cacheの比較では、cache作成に使ったmodelがcacheから読まれることも固定条件です。別model、別quantization、別tokenizer、別chat templateを混ぜると、時間差がprefix再利用によるものか判定できません。

測定前に残すrun sheet

実行していない数値を埋めず、各runで次を保存します。

区分	記録するもの	理由
software	macOS version、MLX LM version、MLX version、実行command	release差とCLI差を追跡する
model	repository revision、quantization、hash、tokenizer、chat template	cacheのmodel選択とtoken列を固定する
prompt	共通prefixのhash、追加質問のhash、token数、機密情報を除いた保存方針	同じprefixを再利用したか確かめる
cache	cache file名、作成時刻、作成model、`—max-kv-size`	file再利用とKV上限を分離する
machine	Mac chip、unified memory、他の大きなprocess、電源状態	memory pressureと温度の影響を隠さない
観測	prefill開始・終了、最初のtoken、完了、RSSまたはmemory pressure、error	時間と資源を混同しない

時刻を採る方法はclient側で統一します。二つのrunで測定器を変えないこと、model download・初回load・warm-upを性能runへ混ぜないことが基本です。cache file作成そのものの時間は、再利用runとは別に記録します。

比較手順：一度に一つだけ変える

1. cacheなしの基準を作る

同じmodelと完全に同じ共通prefix＋質問を使い、通常のmlx_lm.generateでrunします。少なくとも複数回を同じ順序で行い、各runの前後にmodel downloadや他の重いjobを挟まないようにします。ここで観測するのは「最初のtokenまで」「完了まで」「memoryの状態」「error」です。出力の内容はsamplingを固定しても環境差があり得るため、性能と別列に置きます。

2. cache fileだけを追加する

同じ共通prefixをmlx_lm.cache_promptで保存し、追加質問だけをmlx_lm.generate —prompt-cache-fileへ渡します。READMEの説明どおり、cacheは追加promptのprefixとして扱われます。cacheなしrunのpromptと意味が同じか、改行・chat template・generation promptまで含めて確認します。

cache fileが存在するだけでは、再利用の比較は成立しません。prefixを変えたら新しいcache fileを作り、変更前と変更後の結果を混ぜずに記録します。cache内のmodelと実行条件が不明なrunは、採用判断から外します。

3. KV上限は別runにする

長文を扱うため—max-kv-sizeを調べる場合は、Prompt Cache有無の比較を先に終えます。その後、cache file、model、prompt、samplingを固定し、KV sizeだけを一段ずつ変えます。小さい上限でmemoryが下がっても、品質、必要な文脈の保持、完了率が落ちるなら、単純な改善とは扱えません。

4. memory余白を採用条件に入れる

公式READMEは、RAMに対して大きいmodelではmacOS 15以降のwired memory機能に触れています。ただし、これは端末の安全余裕を無視してmodelを載せる根拠ではありません。model、cache、他processを含めたmemory pressureが継続するなら、modelを小さくするか、prefixを短くするか、通常実行へ戻します。管理者権限でのsystem設定変更を、本稿の再現手順には含めません。

解釈で避ける誤り

2回目が速い: Prompt Cacheだけでなく、modelが既にload済み、filesystem cache、thermal stateの影響を除外します。cacheなしとcacheありを交互に実行し、初回を別扱いにします。
memoryが小さい: —max-kv-sizeを下げた結果なら、長い文脈の品質と必要な情報が残っているかを確認します。Prompt Cache再利用の成果とは断定しません。
出力が違う: model、tokenizer、chat template、sampling、追加質問、prefixのどれが違うかを先に比較します。速度だけを見て結果の差を無視しません。
cacheを複数requestで共有する: v0.31.3 releaseにはserverのparallel tool call handling修正が含まれますが、これは任意の並行cache利用の安全性や性能を保証する記述ではありません。並行requestは別の検証課題として扱います。

採用・非採用の判断

Prompt Cacheを使う候補に残すのは、共通prefixが安定し、cacheの入力範囲を説明でき、同じmodel・versionでcacheなしよりprefillの待ち時間を減らせ、memory pressureと出力確認が許容範囲に収まる場合です。prefixが案件ごとに変わる、cacheの保存範囲を管理できない、RAM余白がない、または結果の再現条件を残せない場合は、通常の完全promptへ戻します。

初めてcache fileを作る場合は、MLX LMのPrompt Cache入門：長文を再利用するで最小手順と戻し方を確認してください。Apple Silicon全体のmodel選択は、Macのメモリ別ローカルLLM選びと分けて判断します。

参考資料

MLX LM公式repository：Prompt Cache、rotating KV cache、Large Models（2026年8月8日確認）
MLX LM公式repository：v0.31.3 Release Notes（2026年4月22日公開、2026年8月8日確認）