LMCacheの使い方完全ガイド【インストールから応用まで】

大規模言語モデル（LLM）の活用が広がるにつれて、その推論速度は重要な課題となっています。特に、チャットボットや長文ドキュメントからの情報抽出など、ユーザーとのインタラクションが頻繁に発生するアプリケーションでは、応答速度がユーザー体験に直結します。

LMCacheがない世界を想像してみましょう。あなたは、社内ドキュメントを基にしたAIアシスタントを開発しています。ユーザーが質問するたびに、数万トークンにも及ぶドキュメント全体を毎回LLMに渡し、その都度推論を実行します。初回応答はもちろん、少し質問のニュアンスが変わるたびに、LLMは同じような内容を再処理し、応答までに数秒から数十秒を要します。GPUリソースは常に高負荷で、コストもかさむばかり。ユーザーはイライラし、離れていってしまいます。

しかし、LMCacheがある世界ではどうでしょうか。LLMが一度処理した内容、特にプロンプトの共通部分や、長文コンテキストの埋め込み情報は賢くキャッシュされます。ユーザーが同じドキュメントに対して別の質問を投げかけても、LMCacheが過去の処理結果を再利用するため、初回応答の数分の一の時間で結果が返ってきます。GPUリソースは効率的に使われ、コストも削減。ユーザーはストレスなくAIアシスタントを利用でき、生産性も向上します。

本記事では、このLMCacheについて、その概要からインストール、基本的な使い方、さらには応用的な活用方法まで、詳細なチュートリアルとしてご紹介します。

LMCacheとは

LMCacheは、LLMの推論を劇的に高速化するための「KVキャッシュレイヤー」です。特に、LLMの推論エンジンであるvLLMと連携して動作することを前提としています。

KVキャッシュとは、LLMがテキストを生成する過程で、以前に処理したトークンの「キー（K）」と「バリュー（V）」の情報をメモリに保存しておく仕組みです。LLMは次のトークンを生成する際、このKVキャッシュを参照することで、すでに計算済みの情報を再利用できます。これにより、特に長いプロンプトや、繰り返し使われるプロンプトの処理において、計算量を大幅に削減し、推論速度を向上させます。

LMCacheは、このKVキャッシュを複数のLLMリクエストや、さらには複数のvLLMインスタンス間で共有・管理することを可能にします。これにより、以下のようなメリットが生まれます。

応答速度の向上 (TTFTの削減): 特に初回トークン生成までの時間（TTFT: Time To First Token）が大幅に短縮されます。
スループットの向上: 同じプロンプトプレフィックスを持つ複数のリクエストを効率的に処理できます。
リソースの有効活用: GPUメモリ上のKVキャッシュを共有することで、メモリ効率が向上し、より多くのリクエストを同時に処理できるようになります。

LMCacheは、LLMアプリケーションにおいて、ユーザー体験と運用効率の両面で大きな改善をもたらすために誕生しました。

インストール方法

LMCacheの利用には、Python 3.10以降の環境と、Dockerが必要です。LMCacheは主にDockerイメージとして提供されており、これによりOSを問わず簡単に環境を構築できます。

Dockerのインストール

まず、お使いのOSにDocker環境がインストールされていることを確認してください。もし未インストールの場合は、以下の公式ドキュメントを参考にインストールしてください。

Docker公式ドキュメント: https://docs.docker.com/engine/install/

Dockerがインストールできたら、ターミナルで以下のコマンドを実行し、バージョンが表示されることを確認します。

docker --version

LMCacheライブラリのインストール（開発用途）

LMCacheのコアライブラリを直接インストールする場合、Pythonの仮想環境内で以下のコマンドを実行します。これは主にLMCache自体の開発や、LMCacheを既存のPythonプロジェクトに組み込む場合に利用します。

# 仮想環境の作成とアクティベート
python -m venv venv_lmcache
source venv_lmcache/bin/activate

# LMCacheのGitHubリポジトリをクローン
git clone https://github.com/LMCache/LMCache.git
cd LMCache

# 開発モードでインストール
pip install -e .

しかし、クイックスタートやデモの実行には、Dockerイメージを利用するのが最も簡単で推奨される方法です。

基本的な使い方

LMCacheの基本的な使い方は、vLLMエンジンと連携させてDockerコンテナとして起動し、デモアプリケーションを実行してその効果を体験することです。ここでは、1つのGPUを持つサーバーでのクイックスタート手順を説明します。

前提条件

Python >= 3.10
Dockerがインストール済み
1つのGPUを搭載したサーバー

ステップ1: Dockerイメージのプル

LMCacheが組み込まれたvLLMのDockerイメージをプルします。

docker pull apostacyh/vllm:lmcache-0.1.0

ステップ2: vLLM + LMCacheの起動

LMCacheを有効にしたvLLMエンジンをDockerコンテナとして起動します。model 変数には利用したいモデル名（Hugging Face Hub上のモデル）を指定します。Huggingface cache dir on your local machine は、Hugging Faceモデルのキャッシュを保存するローカルディレクトリのパスに置き換えてください。Your huggingface access token には、Hugging Face Hubへのアクセスに必要なトークンを設定します。

model=mistralai/Mistral-7B-Instruct-v0.2    # 使用したいモデル名に置き換える
sudo docker run --runtime nvidia --gpus '"device=0"' \
    -v /path/to/your/hf_cache:/root/.cache/huggingface \
    -p 8000:8000 \
    --env "HF_TOKEN=your_huggingface_token" \
    --ipc=host \
    --network=host \
    apostacyh/vllm:lmcache-0.1.0 \
    --model $model --gpu-memory-utilization 0.6 --port 8000 \
    --lmcache-config-file /lmcache/LMCache/examples/example-local.yaml

コマンド内のプレースホルダーを、ご自身の環境に合わせて適切に置き換えてください。

/path/to/your/hf_cache: 例えば /home/user/.cache/huggingface など。
your_huggingface_token: Hugging Faceのアクセストークン。

このコマンドは、GPUデバイス0を使用し、ポート8000でvLLMエンジンを起動します。LMCacheの設定ファイルとして /lmcache/LMCache/examples/example-local.yaml を指定しています。

vLLMエンジンが正常に起動すると、以下のようなログが表示されます。

INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

ステップ3: デモアプリケーションの実行

vLLMエンジンが起動したら、LMCacheのリポジトリをクローンし、デモアプリケーションを実行します。このデモは、長いコンテキスト（examples/f.txt）に基づいたQAアプリケーションです。

新しいターミナルを開き、以下のコマンドを実行します。

git clone https://github.com/LMCache/LMCache
cd LMCache/examples/

# openaiクライアントライブラリをインストール
pip install openai

# デモチャットアプリケーションを起動
python openai_chat_completion_client.py 8000

このデモでは、長いコンテキストファイル f.txt を読み込み、それに関する質問と応答を行います。2回目のQA以降は、LMCacheによってTTFT（初回トークン生成時間）が大幅に短縮されることを体感できます。これは、初回で処理されたコンテキストのKVキャッシュが再利用されるためです。

便利な使い方・応用例 3選

LMCacheは、単に推論を高速化するだけでなく、様々なシナリオでその真価を発揮します。ここでは、実際の開発シーンに落とし込んだ3つの応用例を紹介します。

応用例1: 複数のvLLMインスタンス間でのKVキャッシュ共有

大規模なサービスでは、複数のvLLMインスタンスをデプロイすることがよくあります。LMCacheは、これらのインスタンス間でKVキャッシュを共有する機能を提供します。これにより、異なるユーザーからのリクエストや、同じモデルを使う異なるアプリケーションが、共通のプロンプトプレフィックスのキャッシュを再利用できるようになります。

構成の概要: LMCacheのバックエンドサーバーを独立して起動し、複数のvLLMインスタンスがこのバックエンドサーバーを参照するように設定します。

前提条件:

Python >= 3.10
Dockerがインストール済み
2つのGPUを搭載したサーバー（device=0 と device=1 を使用）

手順:

Dockerイメージのプル: LMCacheバックエンドサーバーとLMCache対応vLLMのイメージをプルします。
```
docker pull apostacyh/lmcache-server:0.1.0
docker pull apostacyh/vllm:lmcache-0.1.0
```
LMCacheバックエンドサーバーの起動: 共有キャッシュを管理するLMCacheバックエンドサーバーを起動します。
```
docker run --name lmcache-server --network host -d apostacyh/lmcache-server:0.1.0 0.0.0.0 65432
```
このコマンドは、バックグラウンド（-d）でLMCacheサーバーを起動し、ホストのネットワーク (--network host) を使用してポート65432でリッスンします。

1つ目のvLLMインスタンスの起動: GPUデバイス0を使用し、ポート8000でvLLMインスタンスを起動します。example.yaml は共有キャッシュ設定ファイルです。

model=mistralai/Mistral-7B-Instruct-v0.2    # 使用したいモデル名に置き換える
sudo docker run --runtime nvidia --gpus '"device=0"' \
    -v /path/to/your/hf_cache:/root/.cache/huggingface \
    -p 8000:8000 \
    --env "HF_TOKEN=your_huggingface_token" \
    --ipc=host \
    --network=host \
    apostacyh/vllm:lmcache-0.1.0 \
    --model $model --gpu-memory-utilization 0.7 --port 8000 \
    --lmcache-config-file /lmcache/LMCache/examples/example.yaml

2つ目のvLLMインスタンスの起動: 新しいターミナルを開き、GPUデバイス1を使用し、ポート8001で2つ目のvLLMインスタンスを起動します。同じく example.yaml を参照します。
```
model=mistralai/Mistral-7B-Instruct-v0.2    # 使用したいモデル名に置き換える
sudo docker run --runtime nvidia --gpus '"device=1"' \
    -v /path/to/your/hf_cache:/root/.cache/huggingface \
    -p 8001:8001 \
    --env "HF_TOKEN=your_huggingface_token" \
    --ipc=host \
    --network=host \
    apostacyh/vllm:lmcache-0.1.0 \
    --model $model --gpu-memory-utilization 0.7 --port 8001 \
    --lmcache-config-file /lmcache/LMCache/examples/example.yaml
```
上記2つのvLLMインスタンスは、LMCacheバックエンドサーバーを介してKVキャッシュを共有します。これにより、例えば同じシステムプロンプトや、共通のドキュメントコンテキストを伴うリクエストが、どちらのインスタンスに送られても高速に処理されるようになります。

応用例2: 長文コンテキストQAアプリケーションの高速化

LMCacheは、長文のドキュメントや記事をLLMに与えて質問応答を行うRAG（Retrieval Augmented Generation）のようなアプリケーションで特に有効です。初回質問時にコンテキストがキャッシュされ、以降の質問ではキャッシュが活用されます。

シナリオ: ユーザーが長いFAQドキュメントに対して複数の質問を投げかけるチャットボット。

高速化の仕組み:

ユーザーが最初の質問を送信すると、長いFAQドキュメントがプロンプトとしてLLMに渡されます。
LMCacheは、このドキュメントのKVキャッシュを生成し、保存します。
ユーザーが同じFAQドキュメントに関する2番目の質問を送信します。
LMCacheは、プロンプトの共通部分（FAQドキュメント）がキャッシュされていることを検出し、既存のKVキャッシュを再利用します。
LLMは、新しい質問部分のみを処理すればよくなるため、応答速度が大幅に向上します。特にTTFTの削減が顕著です。

実装例: 基本的な使い方で示した openai_chat_completion_client.py デモがこのシナリオに該当します。このデモは f.txt という長文ファイルをコンテキストとして利用します。

# LMCache/examples/openai_chat_completion_client.py の抜粋（概念的なコード）
import openai
import sys

# vLLM + LMCacheが動作しているエンドポイント
VLLM_ENDPOINT = f"http://localhost:{sys.argv[1]}/v1"

# 長いコンテキストファイルを読み込む
with open("f.txt", "r") as f:
    long_context = f.read()

client = openai.OpenAI(api_key="EMPTY", base_url=VLLM_ENDPOINT)

def ask_question(question_text):
    messages = [
        {"role": "system", "content": f"You are a helpful assistant. Here is the context: {long_context}"},
        {"role": "user", "content": question_text}
    ]
    response = client.chat.completions.create(
        model="mistralai/Mistral-7B-Instruct-v0.2", # モデル名は起動時に指定したものに合わせる
        messages=messages,
        max_tokens=256,
        stream=True
    )
    full_response = ""
    for chunk in response:
        if chunk.choices[0].delta.content:
            full_response += chunk.choices[0].delta.content
            # print(chunk.choices[0].delta.content, end="", flush=True)
    return full_response

# 最初の質問（キャッシュが生成される）
print("--- 1回目の質問 ---")
start_time = time.time()
ask_question("What is the main topic of the document?")
print(f"Time taken: {time.time() - start_time:.2f} seconds")

# 2回目の質問（キャッシュが利用され高速化）
print("--- 2回目の質問 ---")
start_time = time.time()
ask_question("Can you summarize the key points?")
print(f"Time taken: {time.time() - start_time:.2f} seconds")

このように、システムプロンプトやコンテキストとして渡す長文が同じであれば、LMCacheが自動的にキャッシュを管理し、後続の推論を高速化します。

応用例3: チャット履歴に基づく対話システムの最適化

ユーザーとの対話が続くチャットアプリケーションでは、過去の会話履歴が次の応答生成のためのコンテキストとして利用されます。LMCacheは、この会話履歴のKVキャッシュを効果的に管理し、対話の継続的な高速化に貢献します。

シナリオ: ユーザーがAIと複数回やり取りを行うチャットアプリケーション。

最適化の仕組み:

ユーザーが最初のメッセージを送信し、AIが応答します。このとき、最初のメッセージのKVキャッシュが生成されます。
ユーザーが次のメッセージを送信します。この際、前の会話履歴全体がLLMへのプロンプトに含まれます。
LMCacheは、前の会話履歴部分のKVキャッシュを再利用し、新しいメッセージ部分のみを処理します。
会話が長くなるほど、キャッシュされる履歴部分が長くなり、その分だけLLMの計算量が削減され、応答速度が維持されます。

これにより、ユーザーは会話が長くなっても応答速度の低下を感じにくくなり、より自然な対話体験が可能になります。

他ツールとの組み合わせ

LMCacheは単体で動作するものではなく、既存のLLM開発エコシステムと連携することでその能力を最大限に発揮します。

vLLM

LMCacheは、vLLMのKVキャッシュレイヤーとして設計されています。vLLMは、高速なLLM推論のためのオープンソースライブラリであり、LMCacheと組み合わせることで、スループットと応答速度の両面でさらなる最適化を実現します。

組み合わせ方: LMCache対応のvLLM Dockerイメージを利用するか、vLLMにLMCacheプラグインを組み込む形で利用します。本記事で紹介したクイックスタートや応用例は、全てこの組み合わせに基づいています。

Hugging Face Transformers

LMCacheとvLLMは、Hugging Face Hubに公開されている様々なLLMモデルをロードして利用します。

組み合わせ方: vLLM起動時に mistralai/Mistral-7B-Instruct-v0.2 のようにHugging Face Hub上のモデル名を指定するだけで連携できます。モデルの重みはHugging Faceキャッシュディレクトリに保存され、LMCacheが推論を高速化します。

OpenAI API互換クライアント (LangChain, LlamaIndexなど)

LMCache対応vLLMは、OpenAI APIと互換性のあるエンドポイントを提供します。これにより、既存のOpenAIクライアントライブラリや、それらを基盤とするLangChain、LlamaIndexといったLLMオーケストレーションフレームワークとシームレスに連携できます。

組み合わせ方: クライアントライブラリの base_url をLMCache対応vLLMのエンドポイント（例: http://localhost:8000/v1）に設定するだけで、LMCacheの恩恵を受けながらLLMアプリケーションを開発できます。複雑なプロンプトチェーンやRAGパイプラインでも、裏側でLMCacheが推論を高速化します。

Docker / Kubernetes

LMCacheとvLLMはDockerイメージとして提供されており、コンテナベースでのデプロイが容易です。これにより、Kubernetesなどのコンテナオーケストレーションツールと組み合わせることで、スケーラビリティ、可用性、運用管理の面で大きなメリットが得られます。

組み合わせ方: LMCacheバックエンドサーバーと複数のvLLMインスタンスをそれぞれPodとしてデプロイし、ServiceやIngressでルーティングすることで、高負荷なLLMサービスを構築できます。

よくある設定・カスタマイズ

LMCacheの動作は、YAML形式の設定ファイルによって細かくカスタマイズできます。READMEのクイックスタートでは example-local.yaml や example.yaml が指定されていました。これらのファイルでは、主にキャッシュの挙動やストレージに関する設定を行います。

設定ファイルの例（lmcache_config.yaml）

以下は、LMCacheの設定ファイルで考えられる一般的な項目です。具体的な値は、LMCacheのバージョンや利用シナリオによって異なります。

# キャッシュの保存期間 (秒単位)
# キャッシュされたKVペアがメモリに残る最大時間。
cache_ttl: 3600

# キャッシュストアの種類
# 'local' は単一vLLMインスタンス内でのキャッシュ。
# 'distributed' はLMCacheバックエンドサーバーを介した共有キャッシュ。
cache_store_type: distributed

# 分散キャッシュストアの場合のLMCacheバックエンドサーバーのアドレス
# format: "host:port"
lmcache_server_address: "127.0.0.1:65432"

# キャッシュに割り当てるGPUメモリの割合
# vLLMのgpu-memory-utilizationとは別に、KVキャッシュ専用に予約する割合。
# 全体のGPUメモリに対して、キャッシュが占める割合を調整します。
gpu_cache_memory_ratio: 0.1

# キャッシュのフラッシュポリシー
# 'lru': Least Recently Used (最も古く使われたものを破棄)
# 'fifo': First In First Out (最初に入ったものを破棄)
cache_eviction_policy: lru

# キャッシュキーのハッシュアルゴリズム
# プロンプトからキャッシュキーを生成する際に使用されるアルゴリズム。
# 例えば、'sha256' など。
cache_key_hashing_algorithm: sha256

# デバッグログの有効化
# キャッシュヒット/ミスなどの詳細なログを出力するかどうか。
debug_logging_enabled: true

設定ファイルの指定方法:

vLLMを起動する際に、--lmcache-config-file オプションで作成した設定ファイルを指定します。

model=mistralai/Mistral-7B-Instruct-v0.2
sudo docker run --runtime nvidia --gpus '"device=0"' \
    -v /path/to/your/hf_cache:/root/.cache/huggingface \
    -v /path/to/your/lmcache_config.yaml:/lmcache/LMCache/my_config.yaml \
    -p 8000:8000 \
    --env "HF_TOKEN=your_huggingface_token" \
    --ipc=host \
    --network=host \
    apostacyh/vllm:lmcache-0.1.0 \
    --model $model --gpu-memory-utilization 0.6 --port 8000 \
    --lmcache-config-file /lmcache/LMCache/my_config.yaml

Dockerコマンドの -v オプションを使って、ローカルのYAMLファイルをコンテナ内のパスにマウントしている点に注目してください。これにより、ホストマシンで設定ファイルを編集し、コンテナに適用できます。

これらの設定を調整することで、LMCacheの挙動を特定のアプリケーションやインフラストラクチャの要件に合わせて最適化できます。

今日からできる実行プラン

LMCacheの高速化の恩恵を今日から享受するための3つのステップをご紹介します。

ステップ1: 環境の準備とDockerのインストール

まずは、LMCacheを利用するための基盤を整えましょう。

Dockerのインストール: お使いのOSにDockerがインストールされていない場合は、Docker公式ドキュメントを参考にインストールを完了させてください。
GPU環境の確認: LMCacheとvLLMはGPUを利用するため、NVIDIA GPUが搭載された環境を用意し、GPUドライバーが正しくインストールされていることを確認してください。

ステップ2: クイックスタートでLMCacheの速さを体感

環境が整ったら、本記事の「基本的な使い方」セクションに沿ってクイックスタートデモを実行してみましょう。

LMCache対応vLLMのDockerイメージをプルします。
vLLM + LMCacheを起動します。
LMCacheリポジトリをクローンし、デモアプリケーション openai_chat_completion_client.py を実行します。

初回質問と2回目以降の質問で、特にTTFT（初回トークン生成時間）がどれだけ改善されるか、ご自身の目で確かめてください。この体験がLMCacheの導入を後押しするはずです。

ステップ3: 応用例を試す、または既存プロジェクトへの組み込みを検討

LMCacheの基本的な動作を理解したら、次のステップに進みましょう。

複数のvLLMインスタンスでのKVキャッシュ共有: 「便利な使い方・応用例1」を参考に、LMCacheバックエンドサーバーと複数のvLLMインスタンスをデプロイし、分散キャッシュの仕組みを体験してみてください。これにより、より大規模なLLMサービスでのLMCacheの活用イメージが掴めるでしょう。
既存プロジェクトへの組み込み: すでにLangChainやLlamaIndexを使ったLLMアプリケーションを開発している場合、LMCache対応vLLMをバックエンドとして利用することで、簡単に推論の高速化を図れます。クライアントの base_url を変更するだけで、コードの大幅な変更なしにパフォーマンスを向上させることが可能です。

LMCacheは、LLMアプリケーションのパフォーマンスを向上させる強力なツールです。ぜひ今日からその恩恵を享受し、より高速で効率的なLLMサービスを構築してください。

LMCacheの使い方完全ガイド【インストールから応用まで】

LMCacheの使い方完全ガイド【インストールから応用まで】

LMCacheとは

インストール方法

Dockerのインストール

LMCacheライブラリのインストール（開発用途）

基本的な使い方

前提条件

ステップ1: Dockerイメージのプル

ステップ2: vLLM + LMCacheの起動

ステップ3: デモアプリケーションの実行

便利な使い方・応用例 3選

応用例1: 複数のvLLMインスタンス間でのKVキャッシュ共有

応用例2: 長文コンテキストQAアプリケーションの高速化

応用例3: チャット履歴に基づく対話システムの最適化

他ツールとの組み合わせ

vLLM

Hugging Face Transformers

OpenAI API互換クライアント (LangChain, LlamaIndexなど)

Docker / Kubernetes

よくある設定・カスタマイズ

今日からできる実行プラン

ステップ1: 環境の準備とDockerのインストール

ステップ2: クイックスタートでLMCacheの速さを体感

ステップ3: 応用例を試す、または既存プロジェクトへの組み込みを検討

参考文献