pi-custom-model

Pi のカスタムモデル／バリアントモデル

使用する場面

Pi に保存されたデフォルト設定が読み込まれるのは、正確な provider/id がモデルレジストリに存在する場合のみです。Pi にはプロバイダーごとの静的な一覧が同梱されています。そのため、OpenRouter のルーティング用ショートカットバリアント（:nitro ＝ スループット順に並べ替え、:floor ＝ 最安値、:exacto ＝ ツール使用品質）や、新しく追加されたスラッグは一覧に含まれていません。デフォルトを解決できない場合、Pi は組み込みのプロバイダーごとのデフォルト（openrouter の場合は moonshotai/kimi-k2.6）に暗黙的に切り替えるため、Pi がモデルを「リセット」したように見えます。解決方法は、スラッグをカスタムモデルとして登録し、find(provider, id) で一致するようにすることです。

ファイル（グローバル）

• ~/.pi/agent/settings.json — defaultProvider、defaultModel、defaultThinkingLevel
• ~/.pi/agent/models.json — プロバイダーごとに登録するカスタムモデル
• ~/.pi/agent/auth.json — プロバイダーの認証情報（プロバイダーキーが存在することを確認してください）

手順

1. 追加する前に、スラッグが実在することを確認します（例：OpenRouter のモデル／バリアントが存在するか確認します）。id の入力ミスも暗黙的なフォールバックの原因になります。
2. 認証を確認します。 プロバイダーのキーが auth.json（または OPENROUTER_API_KEY などの環境変数）に設定されている必要があります。認証情報がない場合、モデルは登録されても利用できず、引き続きフォールバックします。
3. モデルを models.json の providers.<provider>.models の下に追加します。 組み込みプロバイダー（openrouter、anthropic など）の場合、メタデータだけを指定します。api、baseUrl、認証情報は同梱のデフォルト設定から引き継がれます。例：

   {
     "providers": {
       "openrouter": {
         "models": [
           {
             "id": "z-ai/glm-5.2:nitro",
             "name": "Z.ai: GLM 5.2 (nitro)",
             "reasoning": true,
             "thinkingLevelMap": { "xhigh": "xhigh" },
             "input": ["text"],
             "cost": { "input": 0.95, "output": 3, "cacheRead": 0.18, "cacheWrite": 0 },
             "contextWindow": 1048576,
             "maxTokens": 32768,
             "compat": { "supportsDeveloperRole": false, "thinkingFormat": "openrouter" }
           }
         ]
       }
     }
   }
   

   cost／contextWindow／compat はベースモデルからコピーします（バリアントでも同じ値です）。<pi-pkg>/node_modules/@earendil-works/pi-ai/dist/providers/<provider>.models.js にある同梱エントリーを探してください。実際のモデルがより大きい場合、汎用的な 128k／16k の値をハードコードしないでください。
4. settings.json でデフォルトを設定します。defaultProvider と defaultModel に正確な ID を指定します。defaultThinkingLevel はユーザーの設定のままにします。
5. 検証します。 pi --list-models | grep <id> にモデルが表示され、JSON の構文が正しいことを確認します。必要に応じてスモークテストを実行します：pi --provider <p> --model "<id>" "which model are you?"。

注意点

• 完全一致のみです。 find() は provider と id が完全に一致する場合のみ該当します。保存されたデフォルトの経路では、あいまい一致やコロンの除去は行われません。settings.json と models.json のスラッグはバイト単位で完全に一致している必要があります。
• 暗黙的なフォールバックです。 デフォルトを解決できなくても、Pi はエラーを表示せず、フッターに別のモデルを表示します。これが見分ける手がかりです。
• settings.json だけを編集しないでください。 defaultModel に未登録のスラッグを設定しても何も起きません。実際の解決方法は models.json を編集することです。
• enabledModels（任意）でモデルピッカーに表示するモデルを固定すると、Ctrl+P による切り替えで別のモデルに戻るのを防げます："enabledModels": ["<provider>/<id>:<thinking>"]。
• プロジェクトによる上書き。 リポジトリの .pi/settings.json はグローバル設定を上書きします。デフォルトが特定のプロジェクト内でのみ元に戻る場合は、まずこのファイルを確認してください。
• Pi を完全に再起動してください。レジストリは起動時に読み込まれます。