自備 API 金鑰

在任何方案，包括免費方案，使用自己的模型金鑰或端點執行 Perch。說明網頁版、桌面版與 CLI 的設定方式，以及與內含用量的關係。

Perch 可以使用你的模型憑證執行，而非使用我們的憑證。使用自有金鑰的用量不計入內含 Perch Tokens，因此使用期間不會消耗每月內含用量。

每個方案，包括免費方案都提供此功能。它是一項功能，不是方案等級，因此不需要升級或切換方案。

有兩種類型：

自有雲端金鑰。 模型供應商提供的金鑰，在帳號儲存一次後，即可在網頁版、桌面版與 CLI 使用。
自有端點。 任何支援相容 OpenAI API 的端點，包括在你自己電腦上執行的模型。本機模型僅限 CLI，原因請參閱本機端點。

自有雲端金鑰

在網頁設定一次，就能隨帳號在各處使用，因為金鑰儲存在伺服器端並與帳號關聯，而非存放於單一裝置。金鑰以加密方式儲存，儲存後不會再傳回瀏覽器。

前往 Settings → Models & Keys。
從清單選擇供應商，並貼上 API 金鑰。
按下 Test。這會使用金鑰執行一次實際的小型請求，回報是否成功，以及模型能否呼叫工具。
按下 Save。
在已儲存的金鑰上按下 Use for chat。

第 5 步是常被漏掉的一步。儲存金鑰只是保存它；Use for chat 才會實際將回合路由到該金鑰。啟用後，訊息輸入區的模型選擇器會改為 Your key · <provider>，Settings 會顯示聊天正在使用你的金鑰，且不計量。

若要回到 Perch 託管模型，請關閉 Use for chat。金鑰仍會保留。

金鑰在帳號中共用，但是否使用它由各裝置分別選擇。在瀏覽器啟用，不會同時在 CLI 啟用，反之亦然。這是刻意的設計：你可以讓一個終端機使用自有金鑰，其餘工作階段仍使用 Perch。

任何供應商，任何模型

如果供應商不在清單中，請選擇 Custom (OpenAI-compatible)，並提供 Perch 以下三項資訊：

欄位	範例
Base URL	`https://api.example.com/v1`
API key	你的金鑰
Model id	與供應商的命名完全一致

模型識別碼會原樣傳遞，因此即使 Perch 未曾收錄該模型，只要端點提供它，就能使用。請從供應商文件完整複製識別碼，包括任何前綴。

表單會檢查兩項要求：

基底 URL 必須使用 https，而且必須是公開位址。 私有或內部網路上的任何位址都會遭拒，包括 localhost。我們的伺服器無法連到你的電腦，因此請使用下述 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 設定，不能從網頁版或桌面應用程式設定。這不是為了方便而選擇的限制：兩者的模型呼叫都經過我們的伺服器，而伺服器無法連到你電腦上的 localhost。CLI 在你電腦上的自身程序中執行呼叫，這是唯一實際能連到本機端點的地方。將端點留在本機，也代表位址與任何金鑰都不會離開你的電腦。

任何相容 OpenAI 的端點都可使用，包括 Ollama、LM Studio、llama.cpp 的伺服器與 vLLM。

桌面版尚未推出本機模型支援。在推出之前，請使用 CLI，或在應用程式中使用雲端金鑰。

使用自有金鑰後有何改變

計量。 使用你金鑰的回合不計入內含 Perch Tokens，也不會產生 Perch Token 費用。
模型路由。 Perch 只會路由到你的供應商。它不會悄悄退回 Perch 託管模型，因為那會將提示詞傳到你未選擇的地方，並向你收費。如果端點無法使用，回合會失敗並說明原因。
模型選擇。 Roost 等級選擇器不再適用，因為 Perch 不再替你選擇模型。
其他功能。 工作區、記憶、檢索、引用檢查與其餘代理框架功能，運作方式與使用託管模型時完全相同。

疑難排解

「已接受你的金鑰，但目前沒有此工作區可執行的模型。」 金鑰有效，但該供應商目前沒有可為你的帳號路由的模型。這是如實回報測試失敗，也代表實際回合會失敗。請嘗試其他供應商，或使用 Custom 明確指定模型。

Test 按鈕的測試通過，但實際回合失敗。 請回報問題。通過的測試應該與實際回合路由到完全相同的位置，因此這種不一致是我們這邊的錯誤，而非需要你自行繞過的問題。

「……不支援工具呼叫。」 公開目錄將該模型列為無法呼叫工具，因此 Perch 拒絕儲存，以免任務中途失敗。請選擇支援工具或函式呼叫的模型；目前多數指令微調與程式開發模型都支援。

本機端點無法在網頁儲存。 這是預期行為。請在 CLI 使用 perch byolm set。

回合仍在使用 Perch 模型。 請確認已在目前使用的裝置選取金鑰。儲存金鑰不會改變回合路由：應用程式中須使用 Use for chat，終端機中則是 perch byok use <provider>。perch byok status 與 /status 都會顯示目前使用哪一個。

模型說明託管模型池的內容與各方案包含什麼。
Perch Roost說明自有金鑰所取代的託管路由。
CLI說明其餘命令列功能。

自備 API 金鑰

本頁內容