Pi Agent と llama.cpp ローカルモデル

Pi Agent は llama.cpp のサポートを内蔵しており、クラウド API を必要とせずにローカルでオープンソースの大規模モデルを実行できます。


llama.cpp とは

llama.cpp は高性能な LLM 推論エンジンであり、コンシューマー向けハードウェア上でオープンソースの大規模言語モデルを実行できます。

CPU 推論(量子化技術によるメモリ要件の大幅な削減)と GPU アクセラレーション(CUDA、Metal、Vulkan など)をサポートしています。

Pi Agent はllama.cpp ルーターサーバーを介してローカルモデルと通信します。

Pi Agent 与 llama.cpp 路由器、本地模型文件的链路示意,以及可选的云端路径


llama.cpp の設定

設定は3ステップです:最初に llama-server ルーターを起動し、次に llama.cpp プロバイダーを登録し、最後にモデルをロードして選択します。

llama-server ルーターの起動

パラメータを付けずに-m 或 --modelllama-server を起動すると、ルーターモードに入ります。

モデルパラメータを指定すると、llama-server はシングルモデルモードに入り、モデルディレクトリをスキャンしなくなります。

ルーターは必要に応じてロードまたはアンロードします--models-dirディレクトリ内の GGUF モデルには、一般的なパラメータとして --models-dir(モデルディレクトリ)、--no-models-autoload(自動ロードの無効化)、--jinja(対話テンプレートとツール呼び出しのサポート有効化)、-ngl(GPU にオフロードするレイヤー数)、-c 32768(各モデルのコンテキストウィンドウ)があります。

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

起動後は、/health と /models の2つのエンドポイントを使用して、ルーターに到達できるか、モデルが検出されるかをセルフチェックできます。

llama.cpp へのログイン

Pi Agent 対話モードでは:

/login llama.cpp

この手順ではローカルプロバイダーを登録するだけで、アカウント認証は不要ですが、ルーターのアドレス(デフォルトは http://127.0.0.1:8080)を入力する必要があります。

実行すると、Pi はルーターの URL とオプションの API キーの入力を求めます。ローカルサービスでは通常、API キーは空のままで構いません。

ローカルモデルの管理

使用して/llamaコマンドでモデル管理メニューを開きます:

/llama

メニューで未ロードのモデルを選択して Enter キーを押すと、モデルがメモリにロードされます。

ロード済みのモデルを選択して Enter キーを押すと、モデルがアンロードされます。

メニュー項目を選択Download model...Hugging Face を検索して新しいモデルをダウンロードできます。ロードまたはダウンロード中に Escape キーを押すとキャンセルを確認できます。

メニューは常にルーターの現在の実際の状態を表示し、ロード済みのモデルだけが /model セレクタに表示されます。

ローカルモデルへの切り替え

使用して/modelコマンドでロード済みのローカルモデルを選択します。

ショートカットキーについては、Ctrl+L でモデルセレクタを開き、Ctrl+P でモデル間を順に切り替えます。


おすすめのオープンソースモデル

以下はローカル実行に適したオープンソースのコーディングモデルです:

モデルパラメータ数最小VRAM/メモリ適用シナリオ
Qwen 2.5 Coder7B / 14B / 32B8G / 16G / 32G汎用コーディング、多言語
DeepSeek Coder V216B / 236B16G / 128G+複雑なプログラミングタスク
CodeLlama7B / 13B / 34B8G / 16G / 32Gコード補完、汎用コーディング
Mistral7B8G軽量コーディングアシスタント

ローカルモデルのコーディング能力は通常、クラウドのトップモデル(Claude Sonnet、GPT-4o など)より劣りますが、ネットワークが制限されている、データ機密性の要件が高い、または頻繁に使用する必要があるシナリオでは、非常に優れた代替手段です。


モデルストレージ

モデルディレクトリは llama-server の起動パラメータ--models-dirによって決まります(例:~/models)。モデルのダウンロードも llama.cpp サーバー側で実行されます。

モデルファイルは通常大きいため(数GBから数十GB)、そのディレクトリに十分なディスク容量があることを確認してください。


カスタム llama.cpp サーバー

llama.cpp サーバーがデフォルト以外のポートまたはリモートマシンで実行されている場合、2つの接続方法があります。

ノーコード方式は環境変数を設定することですLLAMA_BASE_URLとLLAMA_API_KEYカスタム llama.cpp サーバーを指すようにします。拡張機能を書く必要も、/login を使う必要もありません。

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

サーバーで API キーが有効になっている場合、llama-server 起動時に同じ --api-key 値を指定し、--host 127.0.0.1 を維持してローカルアクセスに制限してください。

OpenAI 互換 API に接続するだけでよい場合は、models.json 方式の方が簡単です。『DeepSeek への接続』の章を参照してください。リクエストフローを完全に制御する必要がある場合のみ、拡張方式を使用します。

拡張機能内で llama.cpp プロバイダーを登録します:

例

// ファイルパス:~/.pi/agent/extensions/llamacpp-provider.ts
pi.registerProvider("llama.cpp", {
  name: "ローカル llama.cpp",
  baseUrl: "http://localhost:8080/v1",
  apiKey: "local",
  api: "openai-completions",
  // ロード済みモデルの動的検出
  async refreshModels({ signal }) {
    const response = await fetch(
      "http://localhost:8080/v1/models",
      { signal }
    );
    const { data } = await response.json();
    return data.map(({ id }) => ({
      id,
      name: id,
      reasoning: false,
      input: ["text"],
      cost: {
        input: 0,
        output: 0,
        cacheRead: 0,
        cacheWrite: 0,
      },
      contextWindow: 128000,
      maxTokens: 16384,
    }));
  },
});

この動的検出モードにより、Pi Agent は llama.cpp サーバー上で現在ロードされているモデルリストをリアルタイムに取得できます。

ファイルを ~/.pi/agent/extensions/ ディレクトリに保存し、Pi Agent を再起動すると、拡張機能が自動的にロードされ、このプロバイダーが登録されます。

有効になったら /model セレクタを開くと、llama.cpp サーバー上で現在ロードされているモデルを表示し、直接対話できます。


ローカルモデルの限界

ローカルモデルを使用する際は、以下の点に注意してください:

  • ツール呼び出し機能:一部のオープンソースモデルではツール呼び出し(tool calling)能力が弱く、Pi Agent の組み込みツールを正しく使用できない可能性があります
  • 推論速度:GPU アクセラレーションがない場合、推論速度が遅い可能性があります
  • コンテキスト長:ローカルモデルの有効コンテキストウィンドウは通常、クラウドモデルより小さいです
  • 推論レベル:非推論型モデルは常に off で動作し、推論レベル機能を使用できません

ツール呼び出し能力が弱い場合、最も一般的な症状は、モデルがツール呼び出しを実際のツール起動ではなくテキスト出力として扱うことです。

> 查看 src/index.ts 的内容

好的,下面是 src/index.ts 的内容:
import { createAgent } from "pi";
export const agent = createAgent();
...

メッセージ領域にツール呼び出しカードが表示されない場合、モデルは実際には read ツールを呼び出しておらず、自分でファイル内容をでっち上げていることを意味します。

このような場合は、ツール呼び出しのサポートがより優れたモデルに切り替えるか、タスクをより小さなステップに分割することができます。

推奨されるハイブリッド戦略:深い推論や複雑なコーディングが必要な場合はクラウドモデル(Claude Sonnet など)を使用し、日常の簡単なタスクやネットワークが制限されている場合はローカルモデルに切り替えます。

Ctrl+P を使用すると、2つのモデルをすばやく切り替えることができます。

その他の拡張機能