自分のAPIキーを使う

Perchは、Perchのものではなく、あなた自身のモデル認証情報で実行できます。自分のキーでの使用分は、プランに含まれるPerch Tokenにカウントされないため、使用中も毎月のプランに含まれる使用量はそのまま残ります。

この機能はすべてのプランで、無料プランも含めて利用できます。ティアではなく機能なので、アップグレードや切り替えが必要なものはありません。

種類は二つあります。

• 自分のクラウドキー：モデルプロバイダーのキーで、アカウントに一度保存すれば、Web、デスクトップ、CLIから使えます。
• 自分のエンドポイント：OpenAI互換APIを話すものなら何でも使えます。自分のマシンで動いているモデルも含みます。自分のマシン上のモデルはCLI限定です。その理由はローカルエンドポイントを参照してください。

自分のクラウドキー

ウェブで一度設定すれば、キーはデバイスではなくサーバー側でアカウントに紐づいて保存されるため、どこからでも使えます。保存時に暗号化され、保存後にブラウザに送り返されることはありません。

1. Settings → Models & Keysを開きます。
2. 一覧からプロバイダーを選び、APIキーを貼り付けます。
3. Testを押します。キーに対して実際のごく小さなリクエストを一件実行し、成功したかどうかと、そのモデルがツールを呼び出せるかどうかを報告します。
4. Saveを押します。
5. 保存したキーのUse for chatを押します。

手順5が、多くの人が見落とすところです。キーの保存は保存でしかなく、実際にターンをそのキーに通すのはUse for chatです。オンにすると、入力欄のモデルピッカーはYour key · <provider>に置き換わり、Settingsには、チャットがあなたのキーで動いていて課金対象外であることが表示されます。

Perchがホストするモデルに戻すには、Use for chatをオフにします。キーは保存されたままです。

キーはアカウント内で共有されますが、それを使うかどうかの選択はデバイスごとです。ブラウザでオンにしてもCLIではオンにならず、その逆も同じです。これは意図的な動作で、ひとつのターミナルだけを自分のキーで動かし、残りのセッションはPerchのままにする、という使い方ができます。

どのプロバイダーでも、どのモデルでも

プロバイダーが一覧にない場合は、**Custom (OpenAI-compatible)**を選んで、三つの情報を入力します。

モデルIDはそのまま渡されるため、エンドポイントがそのモデルを提供している限り、Perchが知らないモデルでも動作します。プレフィックスも含めて、プロバイダーのドキュメントから正確にコピーしてください。

フォームが強制する要件は二つあります。

• ベースURLはhttpsで、公開アドレスである必要があります。localhostを含め、プライベートネットワークや内部ネットワーク上のアドレスは拒否されます。Perchのサーバーからあなたのマシンには到達できないため、それには後述のCLIの方法を使ってください。
• **モデルがツール呼び出しに対応している必要があります。**Perchは、ファイルの読み取り、コマンドの実行、ツールの呼び出しによって動作します。それができないモデルは、最初ではなく実際の作業の途中で失敗します。モデルが公開モデルカタログに載っていて、そのカタログがツール呼び出し非対応としている場合は、その旨のメッセージとともに保存が拒否されます。カタログに載っていないモデルは通します。新しいモデルやプライベートなモデルの多くは、まだ載っていないためです。

カタログに載っているモデルでは、Perchは実際のコンテキストウィンドウも取得するため、長いコンテキストのモデルは、控えめなデフォルトではなく、その全ウィンドウを使えます。

デスクトップ

デスクトップアプリは同じアカウントでサインインするため、ウェブで保存したキーはすでに使えます。同じパネルがアプリ内のSettings → Models & Keysにあり、動作も同じです。

引き継がれないものがひとつだけあります。デバイスごとのUse for chatの選択です。アプリ内で一度オンにしてください。

自分のマシンで動くモデルは、現時点ではCLI限定です。ローカルエンドポイントを参照してください。

CLI

CLIは同じアカウントでサインインするため、ウェブで保存したキーはどれもすぐに使えます。選択はデバイスごとなので、別途手順が必要です。

perch byok list                  # keys saved on your account
perch byok use openai            # run this terminal's turns on that key
perch byok status                # what turns are running on right now
perch byok off                   # back to Perch-hosted models

セッション内では/byokが同じことをします。/byokだけなら現在の実行元を表示し、/byok <provider>で切り替え、/byok offで戻ります。perch statusと/statusのどちらにもbyokの行があります。

ターミナルを離れずにキー自体を管理することもできます。

perch byok set openai --key sk-...                     # save a key to your account
perch byok set custom --key sk-... \
  --url https://api.example.com/v1 --model acme/model-x  # your own endpoint
perch byok test [provider]                             # probe it with one real request
perch byok remove openai                               # delete the saved key

キーはアカウントに送信され、ウェブのパネルとまったく同じように、そこで暗号化されます。入力したマシンに書き込まれるのは、プロバイダーの選択だけです。

自分のマシン上のモデル

エンドポイントがデバイス上にとどまるため、こちらは別のコマンドです。

perch byolm set <baseUrl> <modelId> [--key <key>]
perch byolm status
perch byolm test
perch byolm clear

たとえばOllamaに対しては次のとおりです。

perch byolm set http://localhost:11434/v1 llama3.1
perch byolm test

--keyは任意です。ローカルのランタイムの多くはキーを必要とせず、Perchはプレースホルダーを送るのではなく、認証ヘッダー自体を省略します。

perch byolm testは小さなリクエストを一件送り、エンドポイントが応答したかどうかと、モデルがツールを呼び出したかどうかを報告します。実際の作業の前に実行してください。ツールを呼び出せないローカルモデルは、そうしなければ動いているように見えて、最初のファイル読み取りで止まります。

ローカルエンドポイント

ローカルエンドポイントはあなたのマシン上にあるため、設定はCLIからのみ行え、ウェブやデスクトップアプリからはできません。これは利便性のために選んだ制限ではありません。ウェブとデスクトップのどちらも、モデル呼び出しをPerchのサーバー経由で実行しており、そのサーバーからはあなたのコンピューターのlocalhostに到達できないためです。CLIは、あなたのマシン上の自分のプロセスで呼び出しを実行します。ローカルエンドポイントに実際に到達できるのは、そこだけです。ここに限定することで、アドレスやキーがあなたのマシンの外に出ることもありません。

OpenAI互換であれば何でも使えます。Ollama、LM Studio、llama.cppのサーバー、vLLMなどです。

デスクトップでのローカルモデル対応は、まだリリースされていません。リリースまでは、CLIを使うか、アプリでクラウドキーを使ってください。

自分のキーを使うと変わること

• 計量：自分のキーでのターンは、プランに含まれるPerch Tokenにカウントされず、Perch Tokenの課金も発生しません。
• モデルのルーティング：Perchはあなたのプロバイダーにだけルーティングします。黙ってPerchのホスト型モデルに切り替えることはありません。それは、あなたが選んでいない場所にプロンプトを送り、あなたに課金することになるからです。エンドポイントが落ちている場合、ターンは失敗し、その旨が表示されます。
• モデルの選択：Perchがモデルを選ぶわけではなくなるため、Roostティアのピッカーは適用されません。
• そのほかすべて：ワークスペース、メモリ、リトリーバル、出典のチェック、ハーネスの残りの部分は、ホスト型モデルでの動作とまったく同じです。

トラブルシューティング

「Your key was accepted, but no model this workspace can run is available.」（キーは受け付けられましたが、このワークスペースで実行できるモデルがありません） キーは有効ですが、そのプロバイダー上で現在あなたのアカウントにルーティングできるモデルがありません。これはテスト失敗の正直な伝え方であり、実際のターンも失敗するという意味です。別のプロバイダーを試すか、Customを使ってモデルを明示的に指定してください。

Testボタンは成功するのに、実際のターンが失敗する。 報告してください。成功するテストは、実際のターンとまったく同じ場所にルーティングされるように作られているため、この特定の食い違いは、回避すべき問題ではなく、こちら側のバグです。

「...does not support tool calling.」（…はツール呼び出しに対応していません） 公開カタログでは、そのモデルはツールを呼び出せないとされているため、Perchはタスクの途中で失敗させるよりも、保存を断りました。ツール呼び出しまたはファンクションコーリングに対応したモデルを選んでください。現在の指示系・コーディング系モデルの多くは対応しています。

ローカルエンドポイントがウェブで保存できない。 想定どおりの動作です。CLIでperch byolm setを使ってください。

ターンがまだPerchのモデルを使っている。 作業しているデバイスでキーが選択されているか確認してください。キーを保存してもターンは切り替わりません。アプリではUse for chat、ターミナルではperch byok use <provider>です。perch byok statusと/statusのどちらでも、現在どちらを使っているかが分かります。

関連ページ

• モデル：ホスト型のプールに何があり、各プランに何が含まれるかを説明しています。
• Perch Roost：ホスト型のルーティングを説明しています。自分のキーは、これを置き換えるものです。
• CLI：コマンドラインの残りの部分を説明しています。