跳至內容

第二家供應商,就是四個欄位,其中三個很容易填錯

加第二支金鑰之前先讀這篇:決定路線通不通的三個欄位、為什麼同一個模型有兩個名字,還有七條路線一次對照。
2026年9月12日
第二家供應商,就是四個欄位,其中三個很容易填錯
OdooBot
route map
Pi Agent 指南 · 第 7 篇

第二家供應商,就是四個欄位,其中三個很容易填錯

你已經接好 OpenRouter,也能用了。加第二支金鑰之前先讀這篇:決定一條路線通不通的三個欄位、為什麼同一個模型有兩個不同的名字,還有附加元件文件記載的七條路線。這裡的每個模型 ID 都當成一個有版本時效的範例看,存檔之前先去查供應商當下的頁面。

7 條路線
一個閘道、五家直接供應商、一個推論主機
3 個欄位
API mode、base URL 跟 thinking format 是失敗的主因
6 個步驟
從建立金鑰到第一次低風險測試
為什麼要比較

從缺的東西出發,不是從排行榜出發

第 6 篇已經講過,設定一條路線可能就夠了,尤其那條路線是 OpenRouter 的時候。所以這裡的問題不是哪家公司勝出,而是: 我目前這條路線缺什麼?

講白一點

沒有人是因為雜誌幫銀行排名,才去開第二個銀行帳戶的。你會開,是因為第一個帳戶做不到你需要的某件具體的事——某種貨幣、某種卡片、公司附近有分行。第二家供應商是同一種決定。如果你講不出那件具體的事,就不需要開這個帳戶。

要比的是原生 API 功能、模型可用性、帳戶管控,跟路線的獨立性。一份通用排行榜,發布那週就過時了,而且就算沒過時,也告訴不了你目前的路線夠不夠用。

flowchart TD
  A["OpenRouter 已經在運作"] --> B{"Can you name what is missing?"}
  B -->|"什麼都不用"| C["留在同一條路線"]
  B -->|"一個原生的 API 功能"| D["一家有文件記載這個功能的直接供應商"]
  B -->|"分開的計費或帳戶控管"| E["一個直接供應商帳號"]
  B -->|"一條路線失敗時的獨立備援路徑"| F["第二條路線,換一家公司"]
  D --> G["對齊 API mode、base URL、
thinking format 跟 model ID"] E --> G F --> G G --> H["先 Test,再用低風險的提示驗證"]
這個決定中間那個框以下的全是設定細節。如果你填不出那個框裡的內容,就留在原地。
判斷的規則是: 留著 OpenRouter,享受目錄的廣度。加一家直接供應商,是為了原生 API 功能、不同的條款、獨立的帳戶控管,或一條獨立運作的路徑。
三個欄位

三個欄位決定一條路線通不通

一筆供應商設定大致上很平常:你自己取的名字、你貼進去的金鑰。但有三個欄位不是喜好問題——它們是通訊協議設定,沒有一個預設值能通吃所有路線。

講白一點

想像寄一封信。base URL 是地址。API mode 是你用什麼語言寫這封信。thinking format 是你怎麼讀回信邊緣潦草寫的那些註記。地址對了、語言錯了:信會送到對的大樓,但沒人看得懂裡面寫什麼。

  • API mode ——一個支援的通訊協議識別碼。大部分路線用 openai-completions。直連 Anthropic 用 anthropic-messages。其他支援的模式還有 openai-responsesgoogle-generative-aimistral-conversationsbedrock-converse-stream
  • baseUrl ——那條路線的端點。相容 OpenAI 的協議,不代表端點就是 OpenAI 的。從別處抄設定時,這是最常見的誤會。
  • thinkingFormat ——特定路線思考資料的解析器。合法值包括 openaiopenrouterdeepseektogetherbasetenzaiqwenchat-templateqwen-chat-templatestring-thinkingant-ling。直連 Anthropic 走原生區塊,透過 anthropic-messages ,這個欄位留空。

要填在哪裡,取決於你在 Add provider 目錄裡選了哪一組。

Pi Agent 的 Settings 對話框,Models 分頁,顯示 Add provider 目錄的上半部:一個 Search providers 搜尋框,接著是 CUSTOM 分組,裡面一張卡片 OpenAI / Anthropic compatible,副標 Custom endpoint format;SUBSCRIPTIONS 分組六張卡片各自標著 OAuth——Anthropic(Claude Pro/Max)、GitHub Copilot、Kimi Code(訂閱制)、OpenRouter OAuth、Radius、xAI(Grok/X 訂閱);接著是 API KEY 分組的開頭,Amazon Bedrock 121 個模型、Ant Ling 3 個模型、Anthropic 14 個模型。
欄位在哪裡目錄從 Settings 的 Models 分頁打開:一個搜尋框,接著每條路線分成三組。
  • CUSTOM 只有一張卡片: OpenAI / Anthropic compatible,副標是 Custom endpoint format。這一項會要你填上面那三個欄位——所以這三個也最容易在這裡出錯。
  • SUBSCRIPTIONS 底下有六張卡片——Anthropic(Claude Pro/Max)、GitHub Copilot、Kimi Code、OpenRouter OAuth、Radius、xAI——各自標著 OAuth。你用登入的方式連線;沒有端點需要打錯。
  • API KEY 是第三組,這個標題講的是驗證方式:用金鑰而不是登入。每張卡片都帶著模型數量——Amazon Bedrock 121 個模型、Ant Ling 3 個、Anthropic 14 個——讓你在打開之前就知道這條路線有多大。
兩個名字,一個模型

第四個欄位是模型 ID,而且是每條路線各自不同的

同一個模型家族,透過閘道連還是直連,回應的字串會不一樣。Claude 是最清楚的例子:兩條路線的四個欄位全部不同。

flowchart LR
  A["你想要一個 Claude 模型"] --> B["路線 A · OpenRouter 閘道"]
  A --> C["路線 B · 直連 Anthropic"]
  B --> D["mode: openai-completions
url: https://openrouter.ai/api/v1
thinking: openrouter
id: anthropic/claude-sonnet-4.5"] C --> E["mode: anthropic-messages
url: https://api.anthropic.com/v1
thinking: 留空,原生區塊
id: claude-sonnet-4-6"]
通往 Claude 的兩條路四個欄位,四種不同的值。這些模型 ID 不是同一個模型可以互換使用的字串。有版本時效的範例
講白一點

模型 ID 不是名字,是目錄編號。同一盞燈,在製造商的目錄裡是一個編號,在轉賣的店家那裡是另一個編號。訂錯編號,什麼都拿不到——不是接近的替代品,就是 model not found

所以要從你設定的那條路線複製 ID,絕對不要從文章或行銷頁面抄——而且要留意標點符號。直連 Anthropic 的命名可能用 4-6 而 OpenRouter 目錄裡的項目用的是 4.5,而一個帶日期的 ID,例如 claude-haiku-4-5-20251001 ,是刻意釘死某個版本的。

Anthropic 在這裡是個例外。 openai-completions 只能透過相容閘道連到 Claude;直接存取用的是 anthropic-messages。比較舊的文件可能把這個模式叫做 anthropic。要選目前文件記載的那個,不然請求可能會失敗,或渲染錯誤。
關於提示快取: Anthropic 的快取用的是 cache_control 這個請求欄位。透過閘道走能不能生效,要看路線、模型跟請求本身。不要假設 Pi Agent 會自動幫你快取每個重複的提示。
路線對照表

七條路線一次看完

這部分值得之後回來查。協議值來自附加元件的基準版本;模型 ID 是撰寫當下記錄的範例。存檔之前,每一個都要對照供應商當下的目錄——託管的模型會在沒有通知的情況下下架或改名。

路線API modeBase URLThinking format模型 ID(要查證)
OpenRouter
閘道
openai-completions https://openrouter.ai/api/v1 openrouter 文件記載的思考型路線用這個;其他留空 anthropic/claude-sonnet-4.5anthropic/claude-opus-5anthropic/claude-haiku-4.5openai/gpt-5meta-llama/llama-3.3-70b-instructgoogle/gemini-2.5-flashdeepseek/deepseek-chat
Anthropic
直連
anthropic-messages https://api.anthropic.com/v1 留空——原生 Messages 區塊 claude-sonnet-4-6claude-opus-4-7claude-haiku-4-5;一個帶日期的 ID,例如 claude-haiku-4-5-20251001 能釘死某個版本
OpenAI
直連
openai-responses https://api.openai.com/v1 複製文件記載的、對應精確模型與路線的值 gpt-5gpt-5-minigpt-5-nano;比較舊的 ID,例如 gpt-4ogpt-4o-minio1-mini 生命週期狀態可能不一樣
DeepSeek
直連
openai-completions https://api.deepseek.com/v1 deepseekdeepseek-reasoner用;一般對話可以留空 deepseek-chatdeepseek-reasoner
GLM(Z.ai/智譜)
直連
openai-completions https://open.bigmodel.cn/api/paas/v4 zai glm-4.6glm-4-flashglm-4-air
Groq
推論主機
openai-completions https://api.groq.com/openai/v1 留空,除非選的模型要求特定的格式 llama-3.3-70b-versatilellama-3.1-8b-instantopenai/gpt-oss-120bopenai/gpt-oss-20b。比較舊的 ID,例如 mixtral-8x7b-32768moonshotai/kimi-k2 可能已經下架
MiniMax
直連
openai-completions https://api.minimax.io/v1 給國際帳號用; https://api.minimaxi.com/v1 給中國大陸帳號用 deepseek ——倉庫實測過的 M 系列格式 MiniMax-M3;原始資料裡的範例還有 abab7-chat-previewabab6.5s-chat
注意多了一個 i MiniMax 有兩個入口—— https://www.minimax.io/ 給國際帳號用, https://platform.minimaxi.com/ 給中國大陸帳號用——憑證不能互通。要用跟你帳號對應的入口與端點。
一個項目可以裝好幾個模型。 供應商、憑證、API mode、端點都一樣的模型可以放在一起:一個 GLM 項目就能列出 glm-4.6glm-4-flashglm-4-air
加一個

六個步驟,不動到已經跑得好好的那條路線

這裡加的是 DeepSeek 當第二條路線。換成其他供應商,做法一樣,只是用它自己文件記載的 API mode 跟端點——上面那張表就是給這個用的。

兩個控制項,兩件不同的事: + Add Provider 是建立一個新項目, + Add Model 是幫既有的項目加一個 ID。你的 OpenRouter 項目不會被改動或取代。

  1. 步驟 1

    建立一支供應商金鑰

    打開 https://platform.deepseek.com/ ,照當下的帳號流程走。建一支金鑰,取名 pi-agent-home ,存進密碼管理器。帳號的要求因供應商跟地區而異。

  2. 步驟 2

    打開 Models 面板,選 Add Provider

    既有的 OpenRouter 卡片留著不動。在 Models 面板裡,點 + Add Provider,或你版本裡對應的控制項。

  3. 步驟 3

    填入四個欄位

    取名為 DeepSeek,選 openai-completions,填入 https://api.deepseek.com/v1,貼上金鑰。thinking format 用 deepseek ,因為這是思考型路線。

  4. 步驟 4

    加入精確的模型 ID

    + Add Model,加入 deepseek-chat,接著加入 deepseek-reasoner。存檔前,兩個都要對照官方模型頁面再確認一次。

  5. 步驟 5

    按 Test,再按 Save

    Test ,等結果出來。如果失敗,先讀懂實際的錯誤訊息再改欄位——一個個猜四個值該改哪個,正是把一條原本能用的路線搞壞的方式。接著點 Save

  6. 步驟 6

    用低風險的提示驗證

    在 composer 裡選新的模型,送一句短的訊息。確認用的真的是你預期的那條路線,再去查供應商自己的用量紀錄。

講白一點

Test 就像電話的撥號音。它證明的是線路接通了,不是接下來的對話會順利進行。一條 Test 一秒就過的路線,遇到很長的生成內容照樣可能逾時。

步驟 6 是大家最容易漏掉的一步,因為它發生在 Settings 之外。

Pi Agent 的模型下拉選單,在 composer 上方打開,列出 GPT-5.3 Codex Spark、GPT-5.4、GPT-5.4 mini、GPT-5.5、GPT-5.6 Luna、GPT-5.6 Sol(旁邊打勾)、GPT-5.6 Terra、GPT-6 Astra。
步驟 6 發生在哪裡模型清單從訊息框下面的按鈕打開。打勾的是 GPT-5.6 Sol。
  • 打勾記號 顯示的是下一則訊息會用哪個模型——這裡是 GPT-5.6 Sol。加一家供應商不會自動改變它;你還是得回到這裡自己選。
  • 這份清單是攤平的。 這台機器上有八個名字,一行一個。加第二條路線只會讓這份清單變長——找步驟 4 加進去的那些模型就好。
  • 它是從 composer 打開的,不是從你填四個欄位的那個面板。Settings 定義的是一條路線;composer 才是實際用它的地方。
依任務挑選

依眼前的工作挑選

先查過當下的目錄,再用這張表參考,不是拿它取代查證。

任務先試這條路線選用的替代方案
日常的家事問題目前 OpenRouter 上比較便宜的模型一個直連的便宜模型——風險低的工作很少需要高階思考型
複雜的 Home Assistant YAML目前 OpenRouter 上夠力的模型直連 Anthropic、DeepSeek 或 GLM——檢查跟測試比品牌更重要
圖片分析目前 OpenRouter 上支援圖片輸入的模型一家直連的多模態供應商——但精確的模型必須接受圖片輸入
長篇 log 分析文件記載的 context 容得下的模型MiniMax 或另一條大 context 的路線——先量一下你的輸入有多大
低延遲的對話目前 OpenRouter 上速度快的路線直連 Groq——自己的環境裡實測延遲
供應商拒絕了一個請求選一個合適的替代模型一條獨立設定的直連路線。不要想辦法繞過安全控管

注意第一欄常常就是你已經有的那條路線。目錄本身就說明了為什麼。

Pi Agent 的 Add provider 目錄下半部,每張卡片都帶著模型數量:OpenCode Go 27 個、OpenRouter 366 個、Qwen Token Plan 18 個、Qwen Token Plan CN 18 個、Qwen Token Plan Individual 9 個、Radius 0 個、Together 21 個、Vercel AI Gateway 237 個、xAI 3 個、Xiaomi 3 個、三個 Xiaomi Token Plan 地區各 2 個、Z.AI 7 個,以及 Z.AI Coding CN 10 個。
為什麼閘道留著就好OpenRouter,一支金鑰後面 366 個模型。Vercel AI Gateway,237 個。這個畫面上其他每一張卡片都比這兩個小。
  • Radius 顯示 0 個模型。 目錄裡有一張卡片,不代表它後面就一定有模型——這就是為什麼步驟 4 要你貼精確的 ID、步驟 5 要你去測試。
我拿到 404,或 model not found
從供應商當下的 docs → Models 頁面複製精確的 ID—— https://openrouter.ai/models 給 OpenRouter, https://console.groq.com/docs/models 給 Groq。檢查大小寫、標點符號、命名空間,跟下架公告。
Test 過了,但實際對話逾時
Test 可能重現不了一次很長的生成。去查供應商的狀態頁、你請求的大小、模型本身、網路路徑,還有 log。在搞清楚哪個請求失敗之前,不要先調高逾時時間。
Groq 的請求回傳速率限制
先檢查 429 回應跟你帳戶的限制,不要假設額度當天就會重置。重置週期跟升級方案因帳戶跟服務而異。
哪條路線最保護隱私?
每一條雲端路線都會收到你送出去的資料。決定供應商會不會拿 API 對話去訓練、保留多久、在哪裡處理、有沒有提供零保留選項的,是官方政策——不是這一頁。閘道本身不會自動增加隱私保護,而本地模型雖然改變了資料流向,卻也帶來本地端的安全維護工作。
Pi Agent 連得到 Perplexity、xAI 或 Google 的模型嗎?
當供應商提供相容 OpenAI 的 API 時,用 openai-completions ,搭配它文件記載的 baseUrl、憑證跟模型 ID——例如 https://api.x.ai/v1,或 Google 的相容端點 https://generativelanguage.googleapis.com/v1beta/openai/。OpenRouter 也可能列出這些模型。
接下來

接下來往哪走

繼續

你現在有地圖了。第 8 篇要講的是這張地圖上一直反覆出現的那個欄位。

Thinking format、思考塊,還有 cache_control 會有專屬的一篇——思考型模型做的事有什麼不同、這在 token 上要付出什麼代價,以及怎麼在對話中途切換模型。

打開完整教學手冊

Pi Agent 入住指南》系列第 7 篇,由 WoowTech 渥屋科技 製作。

內容出自 Woow HA Pi Agent 入住指南,依 CC BY 4.0 釋出。

The Smart Space Solution · 智慧空間解決方案 · © 2026 WOOW Technology Co., Ltd.

網誌: Pi Agent 指南
分享這個貼文