Pi Agent で DeepSeek に接続

DeepSeek は OpenAI 互換の API を提供しているため、Pi に既存の OpenAI アダプタを再利用でき、DeepSeek 専用のアダプタを開発する必要はありません。

接続の核となる作業は次の2つだけです：models.json にプロバイダとモデルパラメータを宣言し、環境変数で API Key を提供します。

全体のアーキテクチャは下図のとおりです：

Pi 接入 DeepSeek 架构图

いわゆる「OpenAI 互換 API」とは、プロバイダの HTTP API プロトコルが OpenAI と一致していることを指します。プロトコルが互換であれば、OpenAI をサポートするあらゆるツールから直接呼び出すことができ、DeepSeek もこれに該当します。

Pi をインストール

Pi は Node.js ランタイムに依存します。インストール前に Node.js が準備できていることを確認してください。

Node.js をインストール

Node.js 公式サイトから対応するシステムのインストーラをダウンロードし、デフォルト設定でインストールしてください。

Pi CLI をインストール

ターミナルで npm を使用してグローバルインストールします：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Linux と macOS ユーザーは、公式インストールスクリプトを使ったワンクリックインストールも可能です：

curl -fsSL https://pi.dev/install.sh | sh

インストールの確認

以下のコマンドを実行し、バージョン番号が正常に表示されればインストール成功です：

pi --version

出力例：

0.83.0

DeepSeek プロバイダの設定

Pi は models.json でカスタムモデルプロバイダを定義します。この節では、DeepSeek を OpenAI 互換 API として接続します。

設定ファイルのパス

OS によって設定ファイルのパスが異なります。使用している OS に応じて対応してください：

OS	設定ファイルのパス
Linux / macOS	~/.pi/agent/models.json
Windows	%USERPROFILE%\.pi\agent\models.json

models.json を作成

以下の内容を設定ファイルに書き込みます：

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 1.74,
            "output": 3.48,
            "cacheRead": 0.145,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        },
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 0.14,
            "output": 0.28,
            "cacheRead": 0.028,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        }
      ]
    }
  }
}

設定項目の説明

以下、models.json で使用する主要フィールドを説明します：

フィールド	型	必須かどうか	説明	デフォルト値
baseUrl	string	必須	DeepSeek の OpenAI 互換 API エンドポイント	https://api.deepseek.com
api	string	必須	接続プロトコル。OpenAI Completions 互換プロトコルを使用することを宣言	openai-completions
apiKey	string	必須	同名の環境変数から API Key を読み取ります。Key を設定ファイルに平文で書く必要はありません。	$DEEPSEEK_API_KEY
contextWindow	number	必須	コンテキストウィンドウサイズ（トークン数）	1000000
maxTokens	number	必須	1回の最大出力長（トークン数）	384000
reasoning	boolean	任意	モデルが思考連鎖（推論）機能をサポートすることを宣言	true
cost	object	任意	入力・出力・キャッシュヒットなどの単価を記録し、Pi のインターフェースでコストを概算するために使用	—
requiresReasoning ContentOnAssistantMessages	boolean	推奨	マルチターン対話で assistant メッセージに reasoning_content フィールドを保持する必要があります。そうしないと互換性の問題が発生する可能性があります。	true
thinkingFormat	string	推奨	DeepSeek 固有の思考内容フォーマットで推論プロセスを解析・表示	deepseek
reasoningEffortMap	object	推奨	Pi の推論強度レベルを DeepSeek が実際にサポートするレベルにマッピング	—

reasoningEffortMap は、Pi の5つの推論レベル（minimal / low / medium / high / xhigh）を DeepSeek がサポートするレベルにマッピングします。xhigh は max にマッピングされますが、それ以外はすべて high に集約されます。

モデルの選択

設定では2つの DeepSeek モデルを宣言しています。主な違いは次のとおりです：

モデル	コンテキストウィンドウ	最大出力	入力単価	出力単価	キャッシュヒット単価	適用シーン
deepseek-v4-pro	1,000,000	384,000	1.74	3.48	0.145	推論能力が高く、複雑なタスクに適しています
deepseek-v4-flash	1,000,000	384,000	0.14	0.28	0.028	応答が速く、コストが低い

単価の単位は100万トークンあたり（米ドル）です。

API Key の取得と設定

まず DeepSeek オープンプラットフォームで API Key を申請します：https://platform.deepseek.com/api_keys。

Linux / macOS でターミナルに環境変数をエクスポート：

export DEEPSEEK_API_KEY="你的 DeepSeek API Key"

Windows（PowerShell）で設定する場合：

$env:DEEPSEEK_API_KEY="你的 DeepSeek API Key"

エクスポートコマンドをシェル設定（~/.bashrc、~/.zshrc、PowerShell Profile など）に書き込むことをお勧めします。新しいターミナルを開くたびに再設定する必要がなくなります。

サンプル内の「あなたの DeepSeek API Key」を実際の API Key に置き換えてください。API Key は機密情報です。適切に保管し、バージョン管理リポジトリにコミットしないでください。

実行とテスト

設定が完了したら、Pi を起動して DeepSeek モデルに切り替えることができます。

Pi を起動

プロジェクトディレクトリに移動:

cd ~/サンプル-test/

そのまま pi コマンドを実行します：

pi

DeepSeek モデルに切り替え

対話インターフェースに入ったら、以下の手順で切り替えます：

入力/modelモデルセレクタを開きます。
deepseek プロバイダを選択し、DeepSeek-V4-Pro または DeepSeek-V4-Flash を選択します。
次に現在のモデルを確認します。

切り替えが完了したら、このミニマルなターミナルフレームワークで直接コーディングを開始できます。

推奨されるテスト手順

以下のチェックリストに従って、接続が完全に機能するかを項目ごとに確認します：

テスト項目	操作方法	期待される結果
認証と接続	一言送信します。例：「こんにちは、サンプル学習プラットフォームについて紹介してください」	正常に返信が得られ、401 / 403 系の認証エラーがなければ、apiKey と baseUrl の設定が正しいことを示します
推論能力	多段階の推論が必要な質問をします。例：最初に分析させてから解決策を提示させる	可視化された思考プロセスが出力されれば、thinkingFormat と reasoning が有効であることを示します
マルチターンのツール呼び出し	Pi にツールを連続呼び出しさせて、ファイルの読み取り、コマンドの実行、コードの変更、結果の検証を行わせます	マルチターン対話が安定し、reasoning_content の欠落によるエラーが発生しない
推論強度の切り替え	/model で medium から xhigh に切り替える	動作が reasoningEffortMap のマッピングに一致し、xhigh が DeepSeek の max に対応する
コスト計算	実際のタスクを数回実行した後、コスト統計を確認します	インターフェースの統計が cost フィールドで設定した単価と一致する

特に「マルチターンのツール呼び出し」は、requiresReasoningContentOnAssistantMessages の設定が正しいかどうかを検証する重要なシナリオです。

よくある問題のトラブルシューティング

接続中に問題が発生した場合は、以下のチェックリストで素早く特定できます。

モデルセレクタに DeepSeek が表示されない

models.json のパスが正しいか確認してください。Windows と Linux / macOS ではパスが異なります。

同時に、JSON 形式に構文エラー（余分なカンマ、閉じられていない引用符など）がないことを確認してください。

認証に失敗

DEEPSEEK_API_KEY 環境変数が正しく設定されていることを確認してください。

注意：pi コマンドを実行するターミナルセッションは、環境変数を設定したセッションと同じである必要があります。

マルチターンのツール呼び出しでエラー

まず requiresReasoningContentOnAssistantMessages と thinkingFormat が上記のとおりに設定されているか確認してください。

より多くのカスタマイズ機能が必要

参考にできるのはPi 公式 models ドキュメント、より完全な設定項目を理解できます。

その他の拡張機能

参考・お気に入り