ローカルLLM開発スタック完全構築【open-notebook + LMCache + headroom + codebase-memory-mcp】

クラウドAPIに依存しないAI環境。それはもはや夢ではありません。私たちは今、手元でパワフルなAIを動かせます。

想像してください。これまでAPIコストを気にしながら開発を進めていた世界。機密性の高いデータをクラウドに送る不安。インターネット接続がなければ何もできない不便さ。これらの制約が、あなたの創造性を妨げていたかもしれません。

しかし、このツールスタックがあれば、その世界は一変します。APIコストはゼロ。データはあなたの管理下に置かれ、完全にプライベートです。インターネットがない場所でも、AIの恩恵を最大限に享受できます。オフラインで、どこまでも深く、自由に思考を広げる環境が手に入るのです。

このツールの組み合わせが最強な理由

open-notebook、LMCache、headroom、codebase-memory-mcp。これら4つのツールは、それぞれが異なる強みを持っています。そして、それらを組み合わせることで、単体では実現できない相乗効果を生み出します。

open-notebookが提供する包括的な知識管理とAIチャット機能。これは、ユーザーが直接触れるAIの「顔」となります。その裏側では、LMCacheがローカルLLMの推論を劇的に高速化します。headroomは、LLMに送るコンテキストを賢く圧縮します。これにより、処理効率と応答速度が向上します。さらに、codebase-memory-mcpは、広大なコードベースから必要な情報を瞬時に引き出す「脳」として機能します。

この連携により、費用を抑えつつ、高速でプライベートなAI開発環境が完成します。クラウドAPIに匹敵する、あるいはそれ以上の体験をローカルで実現するのです。

各ツールの役割と担当領域

このローカルAIスタックを構成する各ツールは、明確な役割分担を持っています。それぞれの特徴を理解することで、全体の仕組みがより深く分かります。

open-notebook：プライベートな知識ベースとAIチャットのハブ

open-notebookは、あなたの知識を管理し、AIと対話するための中心的なプラットフォームです。Google Notebook LMのオープンソース代替として開発されました。PDF、動画、音声、ウェブページなど、多様な形式のコンテンツを取り込めます。取り込んだコンテンツは、フルテキスト検索やベクトル検索で瞬時にアクセス可能です。さらに、このツールは18種類以上のAIプロバイダに対応しています。OllamaやLM Studioなど、ローカルで動作するLLMも柔軟に利用できます。あなたのデータを完全にプライベートに保ちながら、AIによる深い洞察を得られる環境を提供します。

LMCache：ローカルLLMの推論を高速化するキャッシュレイヤー

LMCacheは、vLLMなどのローカルLLM推論エンジンと連携します。LLMの応答速度を向上させるためのキャッシュライブラリです。特に、繰り返し発生するプロンプトや、長いコンテキストを扱う場合に真価を発揮します。過去の計算結果であるKVキャッシュを共有することで、推論の初回応答時間（TTFT: Time To First Token）を大幅に短縮します。これにより、ユーザーはよりスムーズでレスポンシブなAI体験を得られます。ローカルLLMの性能を最大限に引き出すための重要なコンポーネントです。

headroom：LLMへの入力コンテキストを賢く圧縮

headroomは、AIエージェントがLLMに送信するコンテキストを圧縮する層です。ツール出力、ログ、RAGチャンク、ファイル、会話履歴など、あらゆる情報を対象とします。これをLLMに到達する前に圧縮することで、トークン数を60〜95%削減できます。トークン数の削減は、API利用時のコスト削減に直結します。ローカルLLMの場合でも、処理時間の短縮やGPUメモリ使用量の最適化に貢献します。ライブラリ、プロキシ、エージェントラップなど、多様な形式で利用可能です。コンテキストの品質を保ちながら、効率的なLLM利用をサポートします。

codebase-memory-mcp：コードベースの高速インデックスと構造的クエリ

codebase-memory-mcpは、AIコーディングエージェントのための高速かつ効率的なコードインテリジェンスエンジンです。平均的なリポジトリをミリ秒単位でフルインデックス化します。Linuxカーネルのような巨大なコードベースでも、わずか数分で処理が完了します。構造的なクエリに対しては、1ミリ秒未満で応答します。これは、AIがコードを理解し、質問に答える際の基盤となります。単一の静的バイナリとして提供され、macOS、Linux、Windowsに対応しています。AIがコードベースから必要な知識を瞬時に引き出すことを可能にします。

実際のワークフロー

この強力なスタックを構築し、動かすための具体的なステップを解説します。以下の手順で、ローカルAI環境を構築できます。

ステップ1: LMCacheとvLLMのセットアップ

まず、ローカルLLMの基盤となるvLLMとLMCacheをDockerで起動します。これにより、高速な推論環境が整います。

1. 必要なDockerイメージのプル: LMCacheが組み込まれたvLLMイメージをダウンロードします。

   docker pull apostacyh/vllm:lmcache-0.1.0
   

2. vLLM + LMCacheの起動: GPUを使い、指定したLLMモデルをロードしてvLLMサーバーを起動します。 Huggingface cache dir on your local machineとYour huggingface access tokenは、ご自身の環境に合わせて置き換えてください。

   model=mistralai/Mistral-7B-Instruct-v0.2 # 使用したいモデル名に変更
   HUGGINGFACE_CACHE_DIR="/path/to/your/hf_cache" # Huggingfaceキャッシュディレクトリのパス
   HF_TOKEN="your_huggingface_token_if_needed" # Huggingfaceアクセストークン（必要であれば）
   
   sudo docker run --runtime nvidia --gpus '"device=0"' \
       -v $HUGGINGFACE_CACHE_DIR:/root/.cache/huggingface \
       -p 8000:8000 \
       --env "HF_TOKEN=$HF_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
   

   サーバーが起動し、Uvicorn running on http://0.0.0.0:8000というログが表示されれば成功です。

ステップ2: codebase-memory-mcpでコードベースをインデックス化

次に、AIエージェントが参照するコードベースをcodebase-memory-mcpで準備します。

1. codebase-memory-mcpのダウンロードとインストール: GitHubリリースページからお使いのOSに合わせたバイナリをダウンロードし、PATHの通った場所に配置します。

   # 例: Linuxの場合
   wget https://github.com/DeusData/codebase-memory-mcp/releases/latest/download/codebase-memory-mcp-linux-x64
   chmod +x codebase-memory-mcp-linux-x64
   sudo mv codebase-memory-mcp-linux-x64 /usr/local/bin/codebase-memory-mcp
   

2. コードベースのインデックス作成: インデックス化したいリポジトリのルートディレクトリでコマンドを実行します。

   cd /path/to/your/codebase # 対象のコードベースディレクトリへ移動
   codebase-memory-mcp index . # 現在のディレクトリをインデックス化
   

   これで、コードベースの構造情報が利用可能になります。

ステップ3: headroomプロキシの起動

headroomをプロキシとして起動し、LLMへのリクエストを最適化します。

1. headroomのインストール:

   pip install headroom
   

2. headroomプロキシの起動: vLLMが動作するポート（8000）をターゲットに、headroomを別のポート（例えば8787）で起動します。

   headroom proxy --port 8787 --target-url http://localhost:8000
   

   これで、http://localhost:8787へのリクエストは、headroomによる圧縮を経てhttp://localhost:8000（vLLM）に転送されます。

ステップ4: open-notebookのセットアップと連携

最後に、open-notebookを起動し、上記でセットアップしたローカルLLM環境と連携させます。

1. open-notebookのクローンとセットアップ: GitHubリポジトリをクローンし、依存関係をインストールします。

   git clone https://github.com/Open-Notebook-AI/open-notebook.git
   cd open-notebook
   pip install -e . # または poetry install など
   

2. open-notebookの設定:open-notebookは環境変数を通じてLLMプロバイダを設定できます。headroomプロキシを介してvLLMを利用するよう設定します。

   # .env ファイルを作成するか、シェルで直接設定
   export OPENAI_API_KEY="sk-no-key-required" # vLLMはOpenAI互換APIを提供するためダミーキーでOK
   export OPENAI_API_BASE="http://localhost:8787/v1" # headroomプロキシのURLを指定
   export OPENAI_MODEL_NAME="mistralai/Mistral-7B-Instruct-v0.2" # vLLMでロードしたモデル名
   export OPEN_NOTEBOOK_LLM_PROVIDER="openai" # OpenAI互換APIとして扱う
   

3. open-notebookの起動: 設定を反映させてopen-notebookを起動します。

   open-notebook start # 起動コマンドはopen-notebookのドキュメントを参照してください
   

   ブラウザでopen-notebookのUIにアクセスし、知識ベースの作成、コンテンツの取り込み、AIチャットをお試しください。チャットの裏側では、headroomがコンテキストを圧縮し、LMCacheが高速化したvLLMが応答を生成します。codebase-memory-mcpでインデックス化したコードベースも、RAGソースとして利用可能です。

設定ファイル・dotfilesの例

ここでは、主要な設定ファイルや環境変数の設定例を示します。これらは、上記ワークフローの各ステップで参照されます。

LMCacheのvLLM起動設定（example-local.yamlの抜粋）

LMCacheがvLLMと連携する際の基本的な設定です。これはapostacyh/vllm:lmcache-0.1.0イメージ内に含まれるファイルで、通常は変更不要です。

# /lmcache/LMCache/examples/example-local.yaml (イメージ内のパス)
# LMCacheの動作に関する設定
enable_lm_cache: True
cache_dir: "/tmp/lmcache" # キャッシュ保存先
cache_size_gb: 10 # キャッシュサイズ
# その他のLMCache固有の設定...

headroomプロキシの起動スクリプト（start_headroom_proxy.sh）

headroomプロキシをバックグラウンドで起動するためのシンプルなスクリプトです。

#!/bin/bash

# headroomプロキシが使用するポート
HEADROOM_PORT=8787
# LMCacheが動作するvLLMのポート
VLLM_PORT=8000

echo "Starting headroom proxy on port $HEADROOM_PORT, targeting vLLM on port $VLLM_PORT..."
headroom proxy --port $HEADROOM_PORT --target-url http://localhost:$VLLM_PORT &
HEADROOM_PID=$!
echo "headroom proxy started with PID $HEADROOM_PID"
echo "To stop: kill $HEADROOM_PID"

open-notebookの環境変数設定（.envファイル）

open-notebookがローカルLLM環境と連携するための設定です。

# .env
# open-notebookのLLMプロバイダ設定

# vLLMはOpenAI互換APIを提供するため、プロバイダはopenaiとして設定
OPEN_NOTEBOOK_LLM_PROVIDER="openai"

# OpenAI APIキーはダミーでOK
OPENAI_API_KEY="sk-dummy"

# headroomプロキシのURLをAPIベースとして指定
OPENAI_API_BASE="http://localhost:8787/v1"

# vLLMでロードしたモデル名を指定
OPENAI_MODEL_NAME="mistralai/Mistral-7B-Instruct-v0.2"

# 必要に応じて、open-notebookのデータディレクトリなどを設定
# OPEN_NOTEBOOK_DATA_DIR="./data"

これらの設定を適切に行うことで、各ツールがシームレスに連携し、統合されたローカルAI環境が機能します。

よくあるトラブルと解決法

ローカルAI環境の構築は、いくつかの課題を伴うことがあります。一般的なトラブルとその解決策をまとめました。

1. GPUメモリ不足エラー:

   • トラブル: vLLM起動時にCUDA out of memoryなどのエラーが発生します。
   • 原因: GPUのメモリが、指定したモデルのロードや推論に足りていません。
   • 解決法:
     • --gpu-memory-utilizationオプションの値を下げる（例: 0.6を0.5に）。
     • より小さなモデル（例: 7Bから3Bモデルへ）に変更します。
     • 不要なGPUプロセスを終了し、メモリを解放します。

2. Dockerコンテナが起動しない/ポートが競合する:

   • トラブル: docker runコマンドがエラーで終了したり、port is already allocatedといったメッセージが出ます。
   • 原因: 必要なポート（例: 8000番）が他のプロセスによって使用されています。
   • 解決法:
     • sudo lsof -i :8000コマンドで、ポートを使用しているプロセスを確認します。
     • そのプロセスを終了するか、vLLMやheadroomのポート番号を変更します。
     • Dockerコンテナが正しく停止しているかdocker ps -aで確認し、docker rm <container_id>で削除してから再実行します。

3. open-notebookがLLMに接続できない:

   • トラブル: open-notebookのチャット機能でエラーが発生したり、応答が返ってきません。
   • 原因: open-notebookがheadroomプロキシ、またはheadroomがvLLMに到達できていません。
   • 解決法:
     • .envファイルのOPENAI_API_BASEがheadroomプロキシのURL（例: http://localhost:8787/v1）を指しているか確認します。
     • headroomプロキシが起動しているか確認します。
     • headroomの--target-urlがvLLMのURL（例: http://localhost:8000）を正しく指しているか確認します。
     • 各サービスのログを確認し、接続エラーの詳細を特定します。

4. codebase-memory-mcpがコードを認識しない:

   • トラブル: codebase-memory-mcp index .を実行しても、ファイルが見つからない、またはインデックスが生成されません。
   • 原因: コマンド実行時のカレントディレクトリが誤っているか、権限の問題です。
   • 解決法:
     • cd /path/to/your/codebaseで、必ず対象のコードベースのルートディレクトリに移動してから実行します。
     • ファイルやディレクトリへの読み取り権限があるか確認します。

5. headroomによる圧縮効果が実感できない:

   • トラブル: headroomを介しても、LLMの応答速度やトークン数に変化が見られません。
   • 原因: headroomが正しくプロキシとして機能していないか、コンテキストが圧縮対象ではない可能性があります。
   • 解決法:
     • open-notebookが確実にheadroomプロキシを呼び出しているか再確認します。
     • headroomのログを確認し、リクエストがプロキシを通過しているか確認します。
     • 非常に短いプロンプトでは圧縮効果が限定的です。長文のコンテキストを試してみてください。

これらのトラブルシューティングを通じて、安定したローカルAI環境を構築してください。

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

この強力なローカルLLM開発スタックを始めるための具体的な3ステップです。

1. ステップ1: 基本環境の準備: まず、Docker、Python、pipなどの基本的な開発環境を整えます。特にGPUを利用する場合は、NVIDIAドライバーとCUDA Toolkit、DockerのNVIDIAランタイムが必須です。これらのセットアップが、ローカルLLM環境の土台となります。

2. ステップ2: 各ツールの単体動作確認: 次に、LMCacheを組み込んだvLLMを単体で起動し、基本的な推論ができるか確認します。同時に、codebase-memory-mcpで簡単なリポジトリをインデックス化してみましょう。headroomもプロキシとして起動し、既存のOpenAI互換APIエンドポイント（もしあれば）を介して動作確認します。各ツールが個別に正しく機能することを確認することが重要です。

3. ステップ3: open-notebookを通じた統合と活用: 最後に、open-notebookをセットアップし、その設定でheadroomプロキシを経由したvLLMを利用するよう構成します。open-notebookの知識ベースに、codebase-memory-mcpでインデックス化したコードベースの情報をRAGソースとして連携させます。これで、プライベートなローカルAI環境が完成し、あなたの開発や学習に活用できるようになります。

この3ステップを踏むことで、クラウドAPIの制約から解放された、自由でパワフルなAI環境があなたの手元に構築されます。

関連ページ

• ローカルAIスタックの構築ガイド

参考文献

• DeusData/codebase-memory-mcp GitHub
• LMCache/LMCache GitHub
• Open-Notebook-AI/open-notebook GitHub
• headroom.sh GitHub
• vLLM GitHub
• Ollama 公式サイト