llama.cpp

Pi は、llama.cpp ルーターサーバーをサポートします。ルーターは複数の GGUF モデルを検出し、それらをオンデマンドでロードまたはアンロードします。

ルーターをサポートする現在の llama.cpp ビルドを使用してください。 build instructions に従うか、プラットフォームに応じて prebuilt release をインストールしてください。

ルーターを起動する

--model や -m を使用せずに llama-server を開始します。モデルを渡すと、ルーターモードではなく単一モデルモードが開始されます。

llama-server \
  --models-dir ~/models \
  --no-models-autoload \
  --jinja \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 999 \
  -c 32768

重要なオプション:

--models-dir ~/models はローカルの GGUF ファイルを検出します。
--no-models-autoload は、/llama を通じて明示的にロードし続けます。
--jinja は、互換性のあるチャットテンプレートとツール呼び出しを有効にします。
-ngl 999 は、できるだけ多くのレイヤーを GPU にオフロードします。
-c 32768 は、ロードされた各モデルのコンテキストウィンドウを設定します。モデルのネイティブコンテキストを使用するにはこれを省略します。これには大幅に多くのメモリが必要になる可能性があります。

単一ファイルのモデルは、モデルディレクトリに直接置くことができます。マルチモーダルモデルとマルチシャードモデルを別のサブディレクトリに配置します。

~/models/
├── llama-3.2-1b-Q4_K_M.gguf
├── gemma-3-4b-it-Q4_K_M/
│   ├── gemma-3-4b-it-Q4_K_M.gguf
│   └── mmproj-F16.gguf
└── large-model-Q4_K_M/
    ├── large-model-Q4_K_M-00001-of-00003.gguf
    ├── large-model-Q4_K_M-00002-of-00003.gguf
    └── large-model-Q4_K_M-00003-of-00003.gguf

ファイルを手動で追加した後、ルーターを再起動します。モデルごとのコンテキストサイズおよびその他のオプションについては、llama.cpp model presets を使用します。

Piの設定

Pi を起動し、プロバイダーを構成します。

/login llama.cpp

ルーターの URL とオプションの API key を入力します。デフォルトの URL は http://127.0.0.1:8080 です。

環境変数は、/login なしで同じ値を設定できます。

export LLAMA_BASE_URL=http://127.0.0.1:8080
export LLAMA_API_KEY=optional-secret
pi

サーバーが API key を使用する場合は、一致する --api-key 値で llama-server を開始します。ローカルのみのアクセスの場合は、--host 127.0.0.1 を保持してください。

モデルの管理

走る：

/llama

アンロードされたモデルを選択してロードします。
ロードされたモデルを選択してアンロードします。
モデルのダウンロード… を選択し、Hugging Face を検索して、リポジトリと量子化を選択します。正確な owner/repository[:quant] 値も機能します。
ロードまたはダウンロード中に Esc キーを押してキャンセルを確認します。

Hugging Face 検索は、設定されている場合は HF_TOKEN を使用し、次に $HF_TOKEN_PATH、$HF_HOME/token、$XDG_CACHE_HOME/huggingface/token、~/.cache/huggingface/token をチェックします。検索は認証なしでも機能しますが、レート制限が低くなります。 Pi は、ゲートされたリポジトリとそのアクセスページへのリンクをダウンロードする前に警告します。 llama.cpp サーバーはダウンロードを実行するため、選択したリポジトリにアクセスする必要がある場合、そのプロセスには HF_TOKEN も必要です。

他のモデルがロードされている場合、Pi はそれらを最初にアンロードするか、ロードしたままにするかを尋ねます。 Pi はモデルをサイレントにアンロードしたり、モデルファイルを削除したりしません。ルーターは他のクライアントと共有される場合があるため、/llama は常にルーターの現在の状態を表示します。

/modelにはロードされたモデルのみが表示されます。モデルをロードした後、/model を実行して、現在の Pi セッション用にモデルを選択します。

ルーターが切断された場合、/llama には 再試行 と 閉じる が表示されます。 [再試行] は、中断された操作を再実行せずに、再接続してモデルの状態を更新します。

トラブルシューティング

ルーターが到達可能であることを確認します。

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/models

/llama にはモデルがありません: --models-dir、ディレクトリのレイアウトを確認し、ルーターを再起動します。
/model にモデルがありません: 最初に /llama でロードしてください。
ロードが失敗するか、メモリの使用量が多すぎる: -c を下げるか、別のモデルをアンロードします。
サーバーはルーターモードではありません: --model、-m、または -hf を指定せずに起動してください。