服務商協定與模型介面
面對「這個模型能不能用」，請先確認需要的是一般對話、Codemode 圖片/分類操作，還是產品媒體工具。三者共享部分目錄與認證資料機制，但介面不能互換。
v0.1.107 的共同參考是固定 Pi v1.2.0，提交 06a466935536f8c9bcacb2d5efc0fc021be1bdff。下列內容說明已實現介面，不把目錄條目或本機測試擴大成對所有真實 Endpoint、帳號、認證變體的驗收。
具型別的模型目錄
模型目錄按 type 區分操作：
| 型別 | 用途 | 邊界 |
|---|---|---|
chat | 對話及工具呼叫 | 省略 type 時的預設型別；主模型/fallback 選擇該型別 |
image | 具型別的圖片產生 | 供 models.generateImages() 使用 |
classifier | 結構化選擇、評分和布林分類 | 供 models.classify() 使用 |
模型 ID 與 provider、type 一起解析。同一 ID 可屬於不同型別，圖片或分類條目不會靜默變成對話模型。目錄描述包含 API、輸入/輸出型別、限制、費用、相容中繼資料和取樣設定；這些宣告描述路由，不會探測遠端可用性。
高階 providers[].models[] 欄位包括 type、api、base_url、input、output、headers、input_limits、sampling_params、sampling_params_by_thinking_level、compat、capabilities、cost。請遵循所宣告的線上協定和服務商參數。原生取樣依次合併模型預設值、實際推理等級參數、請求參數，後者覆蓋前者；這些欄位不會新增協定，也不保證遠端接受任意選項。
Codemode Models Helpers
Codemode 提供 Models helpers 時，下列非同步函式使用同一份設定目錄與認證資料：
| 函式 | 結果 |
|---|---|
models.getModelsOfType(type, provider?) | chat、image 或 classifier 目錄條目 |
models.getAvailableOfType(type, provider?) | 按服務商啟用狀態與可解析認證資料篩選的條目 |
models.getModelOfType(type, provider, id) | 精確條目，不存在時為 undefined |
models.classify(model, context) | 具型別的分類結果 |
models.generateImages(model, context) | 具型別的圖片結果 |
「Available」是本機認證資料/啟用狀態檢查，不是線上推理測試。腳本收到的目錄描述不含設定 Header；執行時重新解析原始設定模型，修改回傳描述不可將操作重新導向到另一 Endpoint。
已實現的圖片 API 是 openrouter-images；分類 API 為 typesafe-system-one、cloudflare-workers-ai-system-one、llama-cpp-classify 和 openai-decisions。它們的本機請求/結果檢查不代表任意外部部署和帳號都已驗收。
需要先確認有哪些分類模型時，可以在 Codemode 內查詢：
const candidates = await models.getAvailableOfType("classifier");
return candidates.map(model => ({
provider: model.provider,
id: model.id,
api: model.api,
}));
產生圖片時，generateImages 的 context 為 { input: [...] }，其中接受文字和可選的 base64 參考圖片區塊。將結果 output 中的圖片區塊傳給 image(block) 才會展示圖片。classify 接受 state、questions 和模型支援的可選圖片；問題型別為 choice、score、bool。原生失敗保留為具型別的 error/aborted 結果，使用輸出前應檢查 stopReason。這些 helpers 不提供通用 models.chat() 介面。
呼叫分類時，context 必須有物件 state 和非空物件 questions；每個問題填寫 type、instructions、criteria。choice 的 criteria 是非空的「標籤 → 字串含義」物件，score 是非空且從低到高排列的字串描述陣列，bool 是含 true、false 含義的物件。
圖片分類還要求模型支援圖片，images 中使用 { type: "image", data: "<base64>", mimeType: "image/png" }。分類輸出在 answers，圖片產生輸出在 output；後端提供用量時，結果還會包含 usage。
產品圖片產生工具是另一條路徑，目前使用 OpenAI Responses 並儲存工作階段附件。它的 Dashboard 路由不會設定 openrouter-images 或分類記錄。
對話協定
Anyy api_mode | 對應 Pi API | 請求家族 |
|---|---|---|
openai-compatible | openai-completions | OpenAI 風格 Chat Completions，包括相容本機服務 |
openai-responses | openai-responses | OpenAI Responses |
codex-responses | openai-codex-responses | Codex 訂閱 Responses 及其傳輸/工作階段行為 |
anthropic-messages | anthropic-messages | Anthropic Messages |
google-gemini | google-generative-ai | Gemini Generative AI |
同一品牌可能提供多種 Endpoint 契約，選擇品牌不代表協定可以混用。Ollama 和 Ollama Cloud 使用既有 OpenAI 相容家族；Ollama /api/tags 只用於發現模型。
Pi 另外五種 API azure-openai-responses、bedrock-converse-stream、google-vertex、mistral-conversations、pi-messages 在本版沒有獨立原生實現或驗收。相容閘道器確實實現現有五類之一時，可以使用對應契約，但這不代表新增該服務的獨立原生 API。包括原生 Azure、Bedrock 在內的阻止選項仍不可用。
Endpoint 與認證細節
填寫所選 Endpoint 要求的 API 根位址。原生 Anthropic Messages 在所給 Base URL 後追加 /v1/messages?beta=true，不會刪除已有路徑字首。Anthropic 直連根位址為 https://api.anthropic.com，不要重複新增 /v1；自訂代理必須提供最終得到的路徑。
Anyy 在準備請求前解析認證資料。原生 Anthropic 認證遵循有效 Key 和原生 Header/beta 規則，auth_transport 不是強制改變原生 Messages 認證形式的切換開關。OAuth/訂閱設定仍與 Endpoint 綁定。Codex 使用獨立訂閱認證資料，並傳送 Anyy 自己的用戶端身分，預設 originator: anyy，不冒充服務商用戶端。先套用設定中的 model headers，再套用 request headers；後者可覆蓋或刪除該標記。認證與真實的 Anyy User-Agent 仍由 Anyy 管理。
重試、fallback 與虛擬路由
這些機制有不同職責：
| 機制 | 控制範圍 |
|---|---|
| 工作階段自動重試 | 重試可重試的助理錯誤；預設開啟，最多 3 次，從 2,000 ms 開始指數退避，上限 60,000 ms |
| Provider SDK 重試 | 按 retry.provider 重試符合條件的初始傳輸/HTTP 失敗，不重放已經開始串流讀取的回應正文 |
| 設定 fallback | 錯誤策略允許時，按順序嘗試相容 provider/model |
| 虛擬模型回呼 | 把已註冊虛擬選擇解析為實體目錄模型及實際推理等級 |
初始請求不計入工作階段重試次數。計費/帳號限額錯誤不屬於一般暫時性重試，上下文溢位進入上下文復原路徑；取消會結束重試等待。retry.enabled: false 關閉工作階段自動重試，不會同時關閉所有 Provider SDK 行為或已設定 fallback。
高階 Profile 設定使用以下準確的 camelCase 鍵：
retry:
enabled: true
maxRetries: 3
baseDelayMs: 2000
maxAgentDelayMs: 60000
provider:
maxRetries: 0
maxRetryDelayMs: 60000
httpIdleTimeoutMs: 300000
retry.provider.timeoutMs 可選，用於 Provider 請求逾時。httpIdleTimeoutMs 預設 300,000 ms，0 或 disabled 關閉空閒計時器；媒體路由有自己的限制。工作階段重試、SDK 嘗試、fallback 嘗試和 Codex 原生傳輸復原相互區分，因此一個設定不是總請求次數或總耗時上限。
虛擬模型使用內部 pi-virtual 註冊/回呼介面。它不是第六種遠端推理協定，v0.1.107 沒有 YAML 虛擬路由宣告、CLI 精靈或 Dashboard 路由編輯器。已註冊回呼可獲得 user/continuation/retry/direct 上下文並保留分支路由狀態，但必須回傳具有可用認證資料的實體目錄模型，不能指向未註冊模型或遞迴進入另一個虛擬模型。設定 fallback 清單本身不會註冊這種回呼。
日常設定見模型設定與 Dashboard 模型。