受健康檢查驅動的路由

在使用者遇到錯誤之前，將流量路由遠離不健康的部署。背景健康檢查會以可設定的間隔執行，任何失敗的部署都會主動從路由池中移除，而不是等到使用者請求已經失敗之後才處理。

架構

這個問題解決了什麼？

預設情況下，LiteLLM 會將流量路由到所有部署，且只有在某個部署已經讓使用者請求失敗之後，才會停止把流量送往該部署。冷卻系統是反應式的。

健康檢查驅動的路由讓這件事變成主動式：背景迴圈會依可設定的間隔輪詢每個部署。如果某個部署的健康檢查失敗，它會在使用者請求打到之前，立即從路由池中移除。

當您也設定 allowed_fails_policy 時，您可以精確控制每種錯誤類型（驗證錯誤、速率限制、逾時）需要累積多少次健康檢查失敗，才會讓部署進入冷卻。這能避免短暫雜訊造成誤判。

設定

步驟 1：啟用背景健康檢查

背景健康檢查預設為關閉。請在 general_settings 中啟用：

general_settings:
  background_health_checks: true
  health_check_interval: 60    # seconds between each full check cycle

步驟 2：啟用健康檢查路由

general_settings:
  background_health_checks: true
  health_check_interval: 60
  enable_health_check_routing: true  # ← route away from unhealthy deployments

此時，任何健康檢查失敗的部署都會立即從路由中排除，直到下一個檢查週期將其清除。

步驟 3：新增政策以控制多少次失敗會觸發冷卻

如果沒有政策，第一次健康檢查失敗就會將部署標記為不健康。如果您希望更有容錯空間（例如，只有連續 2 次驗證失敗後才採取動作），請使用 allowed_fails_policy：

model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY_SECONDARY

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true

router_settings:
  cooldown_time: 60              # how long a deployment stays in cooldown
  allowed_fails_policy:
    AuthenticationErrorAllowedFails: 1   # cooldown after 2nd auth failure
    TimeoutErrorAllowedFails: 3          # cooldown after 4th timeout

當設定 allowed_fails_policy 時，二元健康檢查過濾器會被繞過。只有冷卻系統會控制路由排除，而且只會在超過您設定的門檻後才觸發。

步驟 4（選用）：忽略暫時性錯誤

健康檢查回傳的 429（速率限制）和 408（逾時）通常表示部署暫時過載，而不是故障。若要完全避免這些情況影響路由：

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  health_check_ignore_transient_errors: true  # 429 and 408 never affect routing

啟用此設定後，只有健康檢查中的硬性失敗（401、404、5xx）會納入冷卻計算。

完整範例

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY_SECONDARY

  - model_name: gpt-4o
    litellm_params:
      model: azure/gpt-4o
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  health_check_ignore_transient_errors: true

router_settings:
  cooldown_time: 60
  allowed_fails_policy:
    AuthenticationErrorAllowedFails: 0   # cooldown immediately on auth failure
    TimeoutErrorAllowedFails: 2          # cooldown after 3 timeouts
    RateLimitErrorAllowedFails: 5        # cooldown after 6 rate limits (if not ignoring transients)

設定參考

設定	位置	預設值	說明
`enable_health_check_routing`	`general_settings`	`false`	將流量路由避開健康檢查失敗的部署
`background_health_checks`	`general_settings`	`false`	健康檢查路由運作必須為 `true`
`health_check_interval`	`general_settings`	`300`	完整健康檢查週期之間的秒數
`health_check_staleness_threshold`	`general_settings`	`interval x 2`	快取健康狀態在被忽略前的秒數
`health_check_ignore_transient_errors`	`general_settings`	`false`	忽略健康檢查中的 429 與 408；這些永遠不會影響路由
`cooldown_time`	`router_settings`	`5`	超過門檻後，部署維持在冷卻狀態的秒數
`allowed_fails_policy`	`router_settings`	`null`	進入冷卻前，各錯誤類型的失敗門檻（如下）

`allowed_fails_policy` 欄位

欄位	錯誤類型	HTTP 狀態碼
`AuthenticationErrorAllowedFails`	API 金鑰錯誤	401
`TimeoutErrorAllowedFails`	請求逾時	408
`RateLimitErrorAllowedFails`	超出速率限制	429
`BadRequestErrorAllowedFails`	請求格式錯誤	400
`ContentPolicyViolationErrorAllowedFails`	內容被過濾	400

其值是指在進入冷卻前可容忍的失敗次數。0 表示第一次失敗就進入冷卻。2 表示第三次才進入冷卻。

需要注意的事項

計數器 TTL 必須長於健康檢查間隔。 allowed_fails_policy 會透過對每個部署遞增一個 failed_calls 計數器來運作。該計數器會在 cooldown_time 秒後過期。如果 cooldown_time 比 health_check_interval 短，則計數器會在每個檢查週期之間重設，失敗次數永遠無法累積。使用 allowed_fails_policy 時，請將 cooldown_time 設為大於 health_check_interval。
```
router_settings:
  cooldown_time: 60       # must be > health_check_interval (30s here)

general_settings:
  health_check_interval: 30
```
AllowedFails: N 表示在第 (N+1) 次失敗時進入冷卻。 計數器檢查是 updated_fails > allowed_fails，因此 0 會在第 1 次失敗時觸發，1 會在第 2 次，2 會在第 3 次。

AllowedFails 冷卻觸發於
0 第 1 次失敗
1 第 2 次失敗
2 第 3 次失敗
如果沒有 allowed_fails_policy，第一次失敗就足夠。 第一次健康檢查失敗會立即將該部署排除在路由之外。當您希望容忍不穩定的檢查時，請使用 allowed_fails_policy。
如果所有部署都不健康，過濾器會被繞過。 流量會持續通過，而不是完全沒有任何部署可用。請求仍會失敗，但路由器會持續嘗試。
健康檢查失敗與請求失敗共用相同的計數器。 當設定 allowed_fails_policy 時，這兩種來源都會遞增同一個 failed_calls 計數器。某個部署若已有 1 次健康檢查失敗，接著又收到 1 次失敗請求，便會達到 AllowedFails: 1 的門檻並進入冷卻。

`AllowedFails`	冷卻觸發於
`0`	第 1 次失敗
`1`	第 2 次失敗
`2`	第 3 次失敗

疑難排解

以 --detailed_debug 啟動 proxy，並尋找以下記錄行：

每次健康檢查週期後（以 DEBUG 等級寫入）：

health_check_routing_state_updated healthy=2 unhealthy=1

當健康檢查失敗遞增計數器並觸發冷卻時（DEBUG 等級）：

checks 'should_run_cooldown_logic'
Attempting to add <deployment_id> to cooldown list

當安全機制因為所有部署都在冷卻中而觸發時：

All deployments in cooldown via health-check routing, bypassing cooldown filter

當安全機制因為所有部署都不健康而觸發時（二元過濾器，沒有 allowed_fails_policy）：

All deployments marked unhealthy by health checks, bypassing health filter

架構​

這個問題解決了什麼？​

設定​

步驟 1：啟用背景健康檢查​

步驟 2：啟用健康檢查路由​

步驟 3：新增政策以控制多少次失敗會觸發冷卻​

步驟 4（選用）：忽略暫時性錯誤​

完整範例​

設定參考​

allowed_fails_policy 欄位​

需要注意的事項​

疑難排解​

架構