LiteLLM Proxy 多模型路由實戰

LiteLLM 是什麼？

LiteLLM 是一個 LLM API 代理，提供標準的 OpenAI 兼容接口，背後可以路由到 100+ LLM 提供商。

Client → LiteLLM Proxy (:4000) → DeepSeek / ModelStudio / Ollama / ...

安裝

pip install litellm[proxy]

配置

litellm_config.yaml：

model_list:
  - model_name: deepseek-flash
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: sk-xxx
  - model_name: deepseek-pro
    litellm_params:
      model: deepseek/deepseek-reasoner
      api_key: sk-xxx
  - model_name: qwen-max
    litellm_params:
      model: dashscope/qwen-max
      api_key: sk-xxx
  - model_name: local-qwen
    litellm_params:
      model: ollama/qwen2.5:7b
      api_base: http://localhost:11434

router_settings:
  routing_strategy: "usage-based"  # 負載均衡
  allowed_fails: 3
  num_retries: 2
  fallbacks:
    - deepseek-flash: [qwen-max, local-qwen]

general_settings:
  master_key: sk-litellm-admin

啟動：

litellm --config litellm_config.yaml --port 4000

在 Claude Code 中使用

{
  "apiKey": "sk-litellm-admin",
  "baseURL": "http://localhost:4000/v1",
  "model": "deepseek-flash"
}

成本追蹤

LiteLLM 自動記錄每次調用的 token 使用和成本。訪問 http://localhost:4000/ui 查看 Dashboard。

路由策略的取捨

路由策略決定請求在後端之間如何分配，選錯會讓成本或延遲失控。

要注意的是，若同一個別名底下掛了不同版本或不同供應商的模型，回應品質會漂移，使用者難以察覺。實務做法是：真正等價的部署才共用一個別名；品質或能力不同的模型用不同別名，交由上層明確選擇。這樣路由只管可用性，品質差異由呼叫方控制。

Fallback、重試與限流的設定要點

重試次數：太少會在後端偶發錯誤時直接失敗，太多則會放大延遲並加重後端負擔。建議先設一個保守值，觀察日誌後再調整。

允許失敗次數：超過門檻後，該部署會被暫時移出輪換，避免持續打到已經不健康的後端。冷卻時間要與後端的恢復時間相匹配，太短會反覆撞牆，太長則白白浪費可用容量。

Fallback 清單：只在特定錯誤（例如限流或伺服器錯誤）下觸發，因此要確認錯誤類型的方向正確。常見錯誤是把 fallback 指向同一個已失效的後端，或清單中的模型別名與上游定義不一致而靜默失敗。

逾時設定：沒有逾時，單一慢請求會拖住整個回應鏈。為每個後端設定合理上限，並與上層的重試策略配合，避免重試堆疊造成雪崩。

此外，不同供應商的錯誤碼語義不一致，同一個數字在不同平台可能代表不同原因，因此錯誤處理要按供應商區分，不要用單一規則套用全部後端。

成本追蹤與預算控制

LiteLLM 會記錄每次調用的 token 使用量並換算成本，但換算依賴內建的價目表，若使用的模型未被收錄，成本會失準，需要自行補上單價。因此第一件事是核對 Dashboard 的數字與實際帳單是否合理，若有偏差就先修正價目。

其次是歸屬：透過不同金鑰區分使用者、專案或環境，成本才能被正確歸類，而不是全部混在一條總帳裡。搭配預算與告警門檻，可以在單一專案吃光配額前收到通知。

要注意本地模型（例如透過 Ollama 提供）不產生 API 費用，但仍消耗本機算力與電力。若把雲端與本地混在同一條路由上，成本數字只反映雲端部分，評估總體開銷時要把本地資源一併計入。

密鑰與部署安全

配置文件中的 api_key 與 master_key 是最容易被忽略的風險點。

• 不要把真實金鑰寫進配置文件後提交到版本庫；用環境變數或受保護的儲存注入。
• 主金鑰權限最大，只發給管理用途；日常呼叫改用限縮權限的虛擬金鑰。
• 對外暴露的代理要加上驗證，別讓 :4000 直接開放在公開網路。
• Dashboard 可能顯示用量與金鑰資訊，存取要設限。
• 本地服務（例如 Ollama）若綁定在 0.0.0.0，同網段的其他裝置也能呼叫，要確認是否符合預期。

驗證方式與常見錯誤

驗證方式

先確認模型清單：呼叫 /v1/models 檢查所有別名是否如預期出現。再用最簡單的請求逐一打不同別名，確認真的落到正確後端，而不是全部被導向同一個。接著做故障演練：故意讓某一個後端不可用（例如填錯金鑰或斷開本地服務），確認 fallback 會接手且回應仍可完成。最後比對 Dashboard 的成本與實際帳單，確認追蹤數字可信。

常見錯誤

• 把主金鑰洩露或直接寫進共享的配置文件。
• 在配置文件裡寫死真實金鑰並提交到版本庫。
• Fallback 清單指向同一個已失效的後端，等於沒有備援。
• 沒有設定逾時，慢後端拖垮整體回應。
• 模型別名與下游貼上的名稱不一致，請求被拒絕或落到非預期模型。
• 同一別名混掛不同能力的模型，品質忽高忽低。
• 忽略雲端與本地混用時的隱私邊界，把敏感資料路由到外部供應商。
• 只看總成本，沒有按專案或使用者拆分，無法定位開銷來源。

檢查清單

• 已確認 /v1/models 的別名清單與規劃一致。
• 每個別名都經實測確認落到正確後端。
• 已定義重試次數、允許失敗次數與冷卻時間。
• 已為每個後端設定逾時。
• 已完成至少一次故障演練，驗證 fallback 生效。
• 已用獨立金鑰區分使用者或專案。
• 已核對 Dashboard 成本與實際帳單。
• 已設定預算與告警門檻。
• 已確認敏感資料不會被路由到不允許的外部供應商。
• 金鑰以環境變數或受保護的儲存管理，未寫入版本庫。

推薦閱讀

• LiteLLM 官方文檔
• DeepSeek V4 指南