キャッシュサービスの管理

キャッシュサービスは、モデルのデプロイが個別の KV キャッシュを保持する代わりに接続する、共有 KV キャッシュです。キャッシュは推論エンジンの外部に置かれるため、同じ Worker 上のデプロイやレプリカが互いのプレフィックスを再利用できます。L2 ストレージバックエンドを使用すると、再起動後やノードをまたいだ再利用も可能です。

キャッシュサービスを接続できるのは、組み込みの vLLM および SGLang バックエンドだけです。デプロイが接続できるキャッシュサービスは、同じクラスター内のものに限られます。

キャッシュサービスの作成

1. Cache Service ページに移動します。
2. Add Cache Service ボタンをクリックし、プロバイダーを選択します。
3. Name を入力します。
4. Version を選択するか、Custom を選択して Container Image を入力します。
5. プロバイダーの設定を入力します。たとえば RAM Size (GiB) は、キャッシュ Server のメモリに保持するキャッシュ容量です。
6. （オプション） Worker Label Selector を設定して、サービスを実行する Worker を制限します。
7. （オプション） L2 Storage Backend を追加して、ローカルディレクトリ、Redis または Valkey、S3 互換オブジェクトストレージなどの、より大きな階層へキャッシュを退避します。複数のエントリーは順番に優先され、読み取りは先頭を優先し、書き込みはすべてに対して行われます。
8. （オプション） Advanced で Parameters と Environment Variables を追加します。複数コンポーネントで構成されるサービスでは、それぞれ異なる実行ファイルを使うため、コンポーネントごとに別のパラメーター一覧を保持します。
9. Save ボタンをクリックします。

デプロイの接続

1. 組み込みの vLLM または SGLang バックエンドを使うモデルのデプロイを作成または編集します。
2. Enable Extended KV Cache を選択します。
3. Cache Backend にキャッシュサービスを設定します。同じクラスター内にあり、選択したバックエンドと互換性を持つキャッシュサービスだけが一覧表示されます。
4. Save ボタンをクリックします。

各インスタンスは、接続したキャッシュサービスと最近のヒット率を報告します。Worker 上にキャッシュインスタンスがないなどの理由でキャッシュなしで起動したインスタンスは、失敗するのではなく、共有 KV キャッシュが有効でないことを報告します。

LMCache でハイブリッド Attention モデルを実行する

ハイブリッドモデルは、Mamba や Gated-DeltaNet（GDN）線形 Attention などの再帰層と、完全 Attention 層を交互に配置します。Qwen3.5 と Qwen3.6 シリーズ、Qwen3-Next、Kimi-Linear、Kimi K3 はいずれもこの種類のモデルです。

再帰層は、トークンごとのキーと値のペアの代わりに固定サイズの状態を保持します。その状態のスナップショットを取得できるのはブロックの末尾だけです。そのため、エンジンは通常の数トークンよりはるかに大きな、モデル自体からサイズを決めるブロックを使います。LMCache は、そのブロック境界と一致する単位でキャッシュを保存する場合にのみモデルに対応できます。どちらも自動ではこの調整を行わないため、既定のままではエンジンが起動を拒否するか、接続してもヒットを記録しません。

手順 1：エンジンが選んだブロックサイズを確認する

vLLM は、Attention ページが再帰状態のページ以上のサイズになるまで Attention のブロックサイズを増やし、デプロイの起動時に結果をログへ出力します。

1

Setting attention block size to 544 tokens to ensure that attention page size is >= mamba page size.

この数値が N です。モデル、データ型、並列化の設定で決まるため、固定値を想定せず、そのデプロイのログから読み取ってください。以下の値は、各モデル本来の精度で単一 GPU 上で実行した際の値です。確認した値の妥当性を判断する参考であり、検索用の対応表ではありません。

手順 2：キャッシュサービスを構成する

• Chunk Size を N またはその倍数に設定します。キャッシュ Server のチャンクサイズは、エンジンのブロックサイズの倍数でなければならず、そうでない場合はキャッシュの登録に失敗します。
• キャッシュ Server の Parameters に --separate-object-groups を追加し、Attention ウィンドウごとに別のオブジェクトグループとして保存します。この設定は既定では無効です。

手順 3：モデルをサービスに接続してデプロイする

デプロイの接続の手順に従い、手順 2 のキャッシュサービスを Cache Backend に選択してモデルをデプロイします。実行中のインスタンスは、接続したサービスと現在のヒット率を報告します。

参考資料

Hybrid Attention Models — 同じ要件と対応する Server フラグについての、LMCache 公式の説明です。

キャッシュプロバイダーのカスタマイズ

選択できるプロバイダーは、このリリースに含まれるものと、インストール済みの拡張機能が追加したものです。プラットフォーム管理者は、別のイメージへの固定、バージョンの追加、GPUStack に含まれないプロバイダーの定義などのために、この集合を独自のドキュメントで置き換えられます。

1. Cache Service ページに移動します。
2. Manage Providers ボタンをクリックします。

3. Provider Source ドロワーで、次の 3 つのソースから選択します。

   • Yaml File：エディターに内容を貼り付けるか、Import をクリックしてファイルを読み込みます。
   • URL：Source URL を入力します。Server は保存時と Update Now のクリック時に取得します。URL は http(s) で、認証情報を含まず、リポジトリのページではなくファイル自体を指す必要があります。ファイルは UTF-8 で、4 MB 以下でなければなりません。
   • Embedded：このリリースに含まれるプロバイダーに戻します。

4. Save ボタンをクリックします。

ドキュメントは保存時に検証されます。このバージョンで読み取れない定義、置換されずにそのまま表示されるプレースホルダー、存在しないフィールド名など、提供できない内容があれば全体を拒否します。最後の点は特に重要です。不明なキーは単純に無視されるため、たとえばコンポーネントの run_command を run_cmd と誤記すると、検証がなければコマンドなしで起動してしまいます。

キャッシュサービスがまだ使用しているプロバイダーまたはバージョンを削除する保存も拒否されます。メッセージには影響を受けるすべてのサービスが示されます。先にこれらのサービスを削除するか、新しいドキュメントに含まれるものへ移行してください。