zophos

← Notes · 32-provider 設定的形狀:空字串表示「沒有」,enum 表示「另一種」.md

provider 設定的形狀:空字串表示「沒有」,enum 表示「另一種」

一個欄位該不該放進所有 provider 共用的結構,看它對每一種 provider 有沒有意義。只對其中一種有意義的,放進 enum 的那一支;「沒有值」可以用空字串,「另一種東西」要用型別表示。

Zophos 支援兩類 provider:

  • 內建的三家:Anthropic、OpenAI、Gemini。網址寫死在程式裡,context window 由 provider 自己回報(Anthropic 200k,其他兩家用保守的 128k)。使用者只要給 API key 和模型名稱。
  • OpenAI 相容的 server:llama.cpp、Ollama、vLLM、LM Studio 這些在自己機器上跑模型的框架,以及 xAI、DeepSeek、OpenRouter 這類雲端服務。它們都支援 OpenAI 的 Chat Completions 格式,一個 provider 就能全部接上。

相容 server 和內建的差在三件事:

  • 網址要使用者給。 server 在哪裡,只有使用者知道。
  • API key 可以沒有。 本地 server 通常不驗證。
  • context window 要使用者給。 本地 server 的 window 是啟動時設定的(llama.cpp 的 -c、Ollama 的 num_ctx),Chat Completions 沒有任何請求問得到它。

為什麼用 Chat Completions

llama.cpp 和 Ollama 其實也接受 Anthropic 的 Messages 格式。那只是 HTTP 請求的格式,server 會轉成模型自己的 chat template,背後跑 Qwen 或 Llama 都可以。但 Zophos 的相容 provider 用的是 Chat Completions,原因有二:

  • 它是每個框架原生、最多人用過的路徑。 Anthropic 格式在這些框架上是後來才加的轉換層。本地模型的 tool call 本來就不太可靠,多一層轉換只會多一個出錯的地方。
  • 不弄髒內建的 Anthropic provider。 沿用它的話,得替模型清單查詢、prompt 快取、thinking 參數各加一個「是不是本地」的判斷。

設定檔的形狀

enum Backend {
    BuiltIn { kind: BuiltIn },
    Compatible { url: String, context_window: u64 },
}
enum BuiltIn { Anthropic, OpenAi, Gemini }

struct ProviderEntry { backend: Backend, models: Vec<String> }

config.json 裡,每個 provider 是一項,用 serde 的 untagged 加 flatten,靠「有 kind 還是有 url」分辨兩種:

"providers": {
  "anthropic": { "kind": "anthropic", "models": ["claude-opus-5-5"] },
  "ollama":    { "url": "http://localhost:11434/v1", "context_window": 32768, "models": ["qwen3-coder"] }
}

這個形狀帶來的保證:

  • 無效的狀態寫不出來。 只有 Compatible 有網址和 window,而且兩個都一定有值。內建的 provider 帶了網址、相容 server 少了 window,這兩種狀態型別直接擋掉。
  • 漏處理會編譯失敗。 建立 client 的 match 列出每一種 backend,沒有 _ => 兜底。以後加一種 provider 卻忘了接上,編譯器會報錯。
  • 內建 provider 的名稱只有一個來源。 BuiltIn::name() 給出名稱,/provider 的選單直接從 BuiltIn::ALL 這個陣列產生。唯一要手動同步的就是這個陣列,因為 Rust 沒有內建的方式列舉一個 enum 的所有值。
  • 名稱和種類是兩回事。 設定檔裡的 key("anthropic")只是名稱,也是它在 keyring 裡的帳號;kind 才決定用哪種 API。所以 "work": { "kind": "anthropic" } 也能用,就是用另一把 key 的第二個 Anthropic 帳號。型別沒有強制名稱等於 kind,因為兩者不一致也不會出錯。

新增 provider 時,是從清單選:內建的三家、已經加過的 server,最後一項是「新增 OpenAI 相容 server」。不讓使用者打 ollama/qwen3-coder 再由程式比對名稱,因為打錯一個字(antropic)就會被當成一台新 server。


沒有選的形狀

用 "" 表示內建。 每個 provider 都有一個 url 字串,內建的寫成空字串。這樣種類就藏在一個字串值裡:建 client 時得比對名稱字串或檢查 url.is_empty(),內建的意外帶了網址、相容 server 沒有網址,型別都擋不住。"" 在這裡不是「網址是空的」,而是「這是另一種東西」,那是種類,該由 enum 表示。

所有欄位攤平。 讓每個 provider 都有 kind、url、context_window,用不到的給預設值或寫死。這不會比較簡單,只是把型別擋掉的錯誤,改成執行時才檢查:

  • 這些欄位對內建 provider 沒有意義。 放進設定檔只有兩種結果:寫了但程式不讀,使用者手改沒效果也沒有錯誤;或是把預設值寫進設定檔,程式更新後,舊設定檔裡的數字不會跟著變。
  • 必填會變成選填。 執行時得檢查網址是不是空的、window 是不是 0。window 是 0 的話,壓縮的門檻也是 0,每一輪都會觸發壓縮。
  • enum 其實少不了。 kind 還是一個四種值的 enum,建 client 時還是要 match。攤平只是把兩個欄位從 enum 裡搬出來。

攤平划算的時機,是每個欄位對每一種 provider 都有作用的時候。例如要讓內建 provider 也能改網址,好走公司的 proxy、LiteLLM gateway 或 Azure OpenAI,那時就該改成 url: Option<String>,None 代表官方網址。那是新功能,等有需要再加。

兩張表。 一張「名稱 → 模型」、一張「名稱 → 網址」。加一個新欄位最省事,舊設定檔也自動相容。但同一批名稱分在兩張表,移除 provider 時兩張都要記得刪。


取捨

API key 沒有就是 ""。 相容 server 不需要 key,送請求時 key 不是空字串才加上認證標頭。內建 provider 的 key 不見時,也一樣用 "" 建出 client,照常送出請求,由 provider 回錯誤。

  • 好處:一條路徑,沒有「內建 provider 沒 key 就不建立」的分支,也不需要另一則提示。401 不會重試,只多一次一定失敗的請求。
  • 代價:key 不見最常見的原因,是 Linux 的 kernel keyring 開機後被清空(WSL 執行 wsl --shutdown 也一樣)。這時使用者看到的是 provider 的「key 無效」,不是「key 被清掉了,請重新輸入」。key 本身沒問題,重新貼上同一把就好,但錯誤訊息不會直接說出這一點。

不讀舊格式的設定檔。 早期版本的設定檔,每個 provider 底下只有一串模型名稱。要讀它,得額外寫一個能接受兩種形狀的 enum 和轉換程式,因為這次改的是欄位的型別,不是加一個欄位,serde 沒辦法自動補預設值。

  • 好處:設定檔的程式碼少了約 50 行,也不用一直帶著一段只為舊資料存在的轉換。
  • 代價:升級後,Zophos 讀不懂舊的 config.json,會把它改名成 config.json.bad,當成沒有設定 provider 啟動。使用者要用 /provider 重新加一次 provider 和模型。API key 存在 keyring 裡,不受影響。apt 版還在 beta,這個代價可以接受。

手改壞的設定檔,錯誤訊息比較籠統。 untagged 靠欄位分辨兩種形狀,kind 拼錯時 serde 只會說「不符合任何一種格式」,不會指出是哪個欄位。


總結

  1. "" 適合表示「沒有」,不適合表示「另一種」。 API key 的空字串就是「沒有 key」;網址的空字串其實在說「這是內建的」,那是種類,種類用 enum。

  2. 只對一種情況有意義的欄位,放進 enum 那一支。 型別就保證它在該在的時候一定在、不該在的時候不存在,執行時不用再檢查。

  3. 攤平適合「每個欄位對每一種都有作用」的時候。 內建 provider 能改網址之前,網址和 window 只屬於相容 server。

  4. 改型別比加欄位貴,貴在舊資料。 加欄位時舊檔相容幾乎免費;改型別就得自己寫轉換。beta 階段選擇不付,代價是升級後重加一次 provider。

  5. 錯誤訊息指向哪裡,是設計決定。 空 key 照常送出,換來一條路徑,代價是 keyring 被清空時,錯誤訊息不會指出真正的原因。